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PREFACE 



This document describes those Multics Commands specifically designed for use by 
individuals filling the roles of (1) system administrators, (2) system maintainers, or (3) 
system operators. 

System administrators provide their sites with a particular Multics operating environment. 
They are responsible for such tasks as controlling and allocating resources; registering 
projects and users; creating load control groups; setting prices on resources; setting 
limits on, and billing for, resource usage; scheduling system activities such as hours of 
operation, shift change times, and unattended service; describing site parameters and 
setting site options; and assuring system security. 

System maintainers configure and tune the operating system to make it comply with 
the special requirements of their sites. They are responsible for such tasks as backing 
up and recovering the system, salvaging and scavenging, analyzing crashes, balancing 
disks, setting up I/O daemons and the message coordinator, metering and tuning, and 
maintaining system databases. 

Operators are responsible for everyday central site services such as system startup and 
shutdown, mounting and demounting of storage devices, operation of the I/O daemons, 
communication with remote users, and first-level maintenance. 

A detailed description of the procedures associated with each of the three user groups 
(administrators, maintainers, and operators) is found in the following three manuals: 

System Administration Procedures (Order No. AK50) 
System Maintenance Procedures (Order No. AM81) 
Operator's Guide to Multics (Order No. GB61) 



The information and specifications in this document are subject to change without notice. Consult 
your Honeywell Marketing Representative for product or service availability. 

© Honeywell Information Systems Inc., 1986 File No.: 1L13 
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This manual is designed as a reference work to be used together with one of the 
procedural manuals specified above. Those manuals function as ''how to** documents, 
making reference, as needed, to the specific commands required to implement the 
various procedures. This manual complements the procedural manuals by providing a 
detailed description of the commands. 

Each conmiand description in this manual provides, minimally, the long and short 
name, syntax line, and function of the program. Standard headings, in the order in 
which they appear, when present, are as follows: 



SYNTAX AS A COMMAND 

SYNTAX AS AN ACT/VE FUNCTION 

FUNCTION 

ARGUMENTS 

CONTROL ARGUMENTS 

ACCESS REQUIRED 

NOTES 

EXAMPLES 



Syntax lines give the order of required and optional arguments accepted by a 
command or active function. Optional portions of syntax are enclosed in braces ({}). 
The syntax for active functions is always shown enclosed in brackets ([]), which are 
required for active function use. To indicate that a command accepts more than one 
of a specific argument, an 'V is added to the argument name (e.g., paths, {paths}. 
{-control_args} ). 

A series of arguments ^idosed in nested braces (e.g., {argl {arg2 {arg3}}}) indicate 
that, while you can omit all the arguments, if you give any one of them, you must 
also give the ones preceding it in the list 



Sigsiificant Changes in GB64-aOA 

In the following lists, the number in parentheses is the section where the command is, 
or was, documented. 

The following commands are new; they contain no change indicators. 

adddev (4) edit_project (2) 

copy_disk (9) lock_mca (2, 4. and 9) 

debu£_fnp (2) restore (9) 

deldev (4) save (9) 

display_log_segment (2) set_process_audit_flags (2) 

display_proc_audit_flags (2) unlock_mca (2, 4, 9) 

edit_process_audit_flags (2) 

The following commands are not privileged: they have been removed from the manual 
They belong in the Commands manual (AG92). 

compare_configuration_deck (2) 
print_configuration_deck (2) 



11/86 



iii 



GB64-00A 



The following commands were accidentally left out for MRll.O: 
display_disk_label (2) 

The following command is obsolete: 
bos (9) 

Section 10 and its 36 commands are obsolete. 
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SECTION 1 
INTRODUCTION 



ORGANIZATION OF THE COMMANDS 

The commands in this document are organized into eight sections (Section 2 
through Section 9). as described below. 



The commands in Section 2 do not require you to be in a "special" 
environment They do, however, require that you have access to the segments and 
directories they reference. At most sites, required access are set only for those 
individuals on the SysAdmin, SysMaint, or Opr projects. 



The commands in Section 3 are entry points (labels) in master.ec. The 
registration and accounting administrator issues a limited set of entry points in 
master.ec. The ^stem administrator can act in the role of registration and accounting 
administrator. 



The commands in Section 4 can be used only when communicating with the 
initializer process. 



The conmiands in Section 5 can be used only when communicating with the 
initializer process. These commands are also contained within admin.ec and require 
that you type "exec" (x) prior to typing the command. 



The commands in Section 6 can be used only when communicating with the 
I/O daemons (i.e., the I/O daemon coordinator and drivers). 



The conmiands in Section 7 are contained within a Honeywell-provided 
limited-service subsystem and are used for communicating with the 
Volume_Dumper.Daemon, the Volume_Reloader.Daemon, or the Volume_Retriever.Daemon. 



The commands in Section 8 are contained within a Honeywell-provided 
limited-service subsystem and are used for conununicating with the Backup.SysDaemon 
and the Dumper.SysDaemon. 
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The commands in Section 9 can be executed only within the restricted 
environment of the Bootload Command Environment (BCE). 

* COMMAND ENVIRONMENTS 

The Multics system "handles" each command by first interpreting the request 
and then invoking the necessary system software components to perform the required 
function. The commands in this manual are organized according to the system 
software components (the environment) required for execution. 

It is the presence of the different software components that forms the 
"command environment" The way in which you enter a specific command environment 
is described at the beginning of each command-specific section. The system software 
components required for command execution are automatically made available when you 
perform the required actions. 



MOVING FROM ONE COMMAND ENVIRONMENT TO ANOTHER 

In some cases you can log in in one environment and move to another 
environment. The Multics system includes various transitional commands that permit 
you to enter two or more command environments while logged in at a single session. 
Figure 1-1 shows the commands that you can issue to move from one command 
environment to another; that process is described below. 



BCE Command Enviromnent 

The first activity in starting or bringing up a Multics system involves the 
* loading of the BCE (Bootload Command Environment) software. While BCE is 
running, you can enter and execute only BCE commands. 



Once the Multics operating system software is bootloaded and the initializer 
process is active, it is not possible, without executing the shutdown command, to 
t reenter the BCE command environment 



Initializer Command Environment 

The initializer process is the system control process for Multics. The initializer 
process is created automatically as a result of a successful Multics bootload operation. 



The initializer process can be active in ring 1 or 4. If the "star" argument was 
« used with the BCE boot command, then the initializer process moves directly to ring 4 
without pausing in ring 1. The system is also made ready for normal user sessions 
(users can log in from remote terminals). 
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If Multics is not booted with the boot star command, the initializer is first 
brought to command level in ring 1. The initializer remains in ring 1 until the 
operator moves it to ring 4 using the standard command or the multics command. 
The operator must then issue the startup conunand or the go command to make the 
system available for normal user sessions (users can log in from remote terminals). 



You use the initializer conmiands and the initializer exec commands to 
communicate with the initializer process. Certain initializer commands can be used 
only when the initializer process is operating in ring 1. Others can be used only when 
the initializer process is operating in ring 4, Some can be used at either time. The 
description of the initializer commands in Section 4 indicates when the individual 
command can be used. The initializer exec conunands can be used only when the 
initializer is operating in ring 4. 



The initializer process remains active as long as the system is running. In its 
normal mode of operation the initializer responds only to initializer commands or 
initializer exec commands. Sometimes, however, it is desirable to use the initializer 
process to execute a "normal" Multics command (i.e., any command that is not an 
initializer command, an initializer exec command, or a BC£ command). To use the* 
initializer to execute a "normal" command you must enter the initializer admin mode 
by issuing the admin conmiand. When in admin mode the initializer process responds 
to **normal" conmiands instead of to the initializer commands or the initializer exec 
commands. 



Once in admin mode you can shift back to tht initializer command 
environment by issuing the admin_mode_exit conmiand. Alternatively, if you want to 
remain in admin mode but want to execute a single initializer command from time to 
time, you can do the following: 

1. if you want to enter an initializer conmiand (excepting the exec conmiands), you 
must use the sc^command together with the desired initializer conunand, as in 

sc_coinmand force__reset 

2. If you want to enter an initializer exec command, you must use the ec admin 
conmiand together with the desired exec command, as in 

ec admin attended 



While in the initializer command environment, you can communicate with the 
system daemon process(es) by the initializer reply command. You use the reply 
command together with the daemon driver label and the daemon command, as in 

reply prta go 



If you want to interrupt daemon execution while in the initializer process, you 
must issue the initializer quit command (and not press the ATTN or INTERRUPT 
key). 
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User Command Environment 

Once the bootload/initialization sequence is complete the system becomes 
available for normal user sessions. Users log in at remote terminals to perform 
assigned work. In a normal session you can use a wide variety of commands, 
including the privileged commands (see Section 2) as well as the commands described 
in the Commands manual (AG92). 



While in the user command environment, you can*t use any of the ''special** 
environment commands described in this manual; you can, however, move to those 
special environments by using transitional commands: 

1. If you want to enter an initializer command (excepting the exec commands), you 
must use the send_admin_command command (which enters initializer admin mode) 
and the sc_command command together with the desired initializer command, as in 

sac sc_coinmand maxu auto 

2. If you want to enter an initializer exec command, you must use the send_adniin_command 
command and the ec admin command together with the desired exec command, as 
in 

sac ec admin attended 

3. If you want to submit a "normal" command to the initializer process, you must 
enter initializer admin mode by using the send_admin_command command together 
with the selected "normal" command, as in 

sac set__systein__conso1e -reset 

4. If you want to enter a daemon command, you can use the send_daemon_command 
command, as in 

send_da«non_command quit bk 

Alternatively, you can use the send_admin_command command and the sc_command 
command together with the initializer reply command, the daemon driver label, and 
the desired daemon command, as in 

sac sc_coimnand reply prta go 

5. If you are a system administrator, you can enter an accounting command by 
changing your working directory to >udd>SysAdmin>admin (see Section 3) and using 
the ec master command together with the selected accounting command, as in 

ec master bill prepare 
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Registration and Accounting Command Environment 

A registration and accounting administrator is restricted by a special process 
overseer to a limited set of commands and cannot move to another command 
environment If you are a system administrator, you can move into, or out of, the 
registration and accounting command environment by changing your working directory 
(see Section 3). 



Daemon Ommand Environment 



The I/O daemon command environment uses a special process overseer 
(iod-overseer) and a special set of search rules; you can't shift from this environment 
to another. The commands in the volume backup daemon command environment are 
contained within a Honeywell-supplied limited-service subsystem; you can't shift from 
this environment to another. The commands for two of the hierarchy backup daemons 
(Backup.SysDaemon and Dumper.SysDaemon) are also contained within a 
Honeywell-supplied limited-service subsystem; you can't shift from this environment to 
another. 



GETTING ONLINE HELP WITH COMMANDS 

There are information segments (info segs) for the commands in this manual in 
the following directories: 



Commands 
Commands in Section 2 
Commands in Section 3 

r^_-.._^~ ; ~. c^^4.:^-. i. 
wwiiimaiiua i ii ,»cv.,Liuii t 

(Ring k commands only) 

CoiiRnands in Section k 
(Ring 1 commands only) 



Commands 
Commands 
Commands 
Commands 

Commands 



n Section 5 
n Section 6 
n Section 7 
n Section 8 
n Section 9 



Di rectories 
>doc>pr i vi leged 
>doc>ss>account i ng 
>doc>S5>operator 

>doc>ss>r l_i n i t i a 1 i zer 

>doc>ss>operator 
>doc>ss> i o__daemon 
>doc>pr i vi 1 eged 
>doc>pr i vi leged 
>doc>ss>bce 
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If you're in the user command environment, the volume backup limited-service 
subsystem, or the hierarchy backup limited-service subsystem, you can use the user 
help command to look at the above info segs. When using the help command, 
however, you must specify the absolute pathname of the info seg, as in the following 

help >doc>privi 1eged>set__system_console 

Alternatively, you can add one or more directories to your info search list by adding 
a line to your start_up.ec; for example, 

asp info >doc>pr i v i 1 eged 

Then, you can look up info segs in the directories without having to specify the 
absolute pathname; for example, 

help set_system_console 



If you're in the ring 4 initializer command environment, you can look at info 
segs for ring 4 initializer conmiands by using the initializer help command; for 
example, 

help down 



If the info seg you want to look at is for an exec command, you must specify 
the name in the format "x.command," as in 

help X. attended 



If you're in the ring 1 initializer command environment, the registration and 
« accounting command environment, the I/O daemon command environment, or the BCE 
command environment, you can't look at info s^. 
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DAEMON ACCOUNTING 
EXEC COMMANDS COMMANDS 



Figure 1-1. Moving From One Command Environment to Another 
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SECTION 2 

PRIVILEGED MULTICS COMMANDS 



The commands in this section do not require you to be in a "special" 
environment. You can use these commands while logged in at a remote terminal in a 
normal user session. However, these commands do perform operations on "privileged" 
data bases and tables and. consequently, can be used only by selected personnel 
(administrators, operators, and maintainers). Thus, while these commands are potentially 
available to all users, they can be executed only by personnel who have previously 
been given access to the segments and directories referenced by the commands. Before 
using any of these commands, you should check with your system administrator to 
determine if you are permitted to perform the desired operation. 
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add mail table enirv add_mail_table entry 



Name: add mail table entry 

SYNTAX AS A COMMAND 

add_ma i l_tab 1 e_entry name {address} {-contro1_args} 
FUNCTION 

adds an entry to the mail table and specifies the entry's mailing address. This 
command is used by system administrators to specify names, usually names of users on 
other systems, that can be used to designate mailboxes (Person_id.Project_id). mailing 
lists, and Forum meetings. The name must not already exist in the mail table or the 
person name table (PNT). Names are not distinguished by case (e.g.. Sackman and 
sackman are the same name). 

ARGUMENTS 

name 

is a string thai specifies the name to be given to this mail table entr\. It must 
be enclosed in quotation marks if it contains blank spaces. 

address 

is a destination specifier, that is. a mailing address in the form, used by the 
-mailbox or -user control arguments (see below). It can be used instead of the 
-mailbox or -user control arguments. 

CONTROL ARGUMENTS 

-acs_path path 

specifies the Access Control Segment (ACS) which controls who may update the 
entry's mail address, rw access to the ACS indicates that a user ma\ update the 
entry. If this is not specified or is the null siring, only users with access to 
mail_table_priv_ may update the entry. 

-alias name 

specifies an alternate name for the name being defined. If this control argument 
is specified multiple times, all the names are defined as aliases for the entry. 

-log path 

specifies the pathname of a logbox and is equivalent to: 

-mai Ibox >udd>Proj ect_l d>Person_i d>Person_i d . sv .mbx 



-TVI»J-iTK/-iV T^OlVl — tV<Kv T«OtV< 



specifies the pathname of a mailbox. The suffix "mbx" is added if necessary. 



-mailing_list path, -mis path 

specifies the name of a mailing list. The suffix "mis' 
archive component pathname convention is accepted. 



is added if necessary. The 
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add_maiLtable_entry 



add_mail_table_entry 



-meeting path, -mtg path 

specifies the pathname of a Forum meeting. The suffix ''control" is added if 
necessary. 

-save path, -sv path 

specifies the pathname of a savebox. The suffix "sv.mbx" is added if necessary. 

STR -at FSystem {-via RelayN...-via Relayl} 

specifies an address on another computer system. STR identifies the user (or 
group of users) to receive the message and is not interpreted in any way by the 
local system. FSystem is the name of the foreign system where the address is 
located. If you give no -via, FSystem must be one of the names of a foreign 
system in the local system's network information table (NIT). If, however, you 
give -via, the foreign system name does not need to be known to the local 
system. 

If you specify -via, they identify an explicit route to be used to reach the 
foreign system. In this case Relayl must be one of the names of a foreign 
system in the local system's NIT. Mail destined for this foreign address is 
forwarded to the system identified in Relayl. From there it is forwarded to the 
system identified as Relay2, and so on until it reaches the system identified as 
RelayN, where it is delivered to the system on which the foreign address actually 
resides. Wh^ the NIT is querried for either FSystem or Relayl, the query is 
performed in a case-insensitive manner. 

-user Person_id.Project_id 

specifies the given user's default "mailbox under the specified project This control 
argument is equivalent to 

-mai Ibox >udd>Project_id>Person_id>Person_id.mbx 
EXAMPLES 
The command line 

add_mai l_tabie_entry "Mary Lutyens" MLutyens.Mktg -at SystemA 

links the name John Jones to MLutyens.Mktg on SystemA so that any time the name 
Mary Lutyens appears in an address used by llie send_mail command. Executive Mail, 
or Emacs Mail, the message is sent to MLutyens.Mktg on SystemA. 

The command line 

add_mai l_table_entry "Mary Lutyens" MLutyens.Mktg -at SystemA 
-al ias ML 

links the name ML, as well as Mary Lutyens, to the mailbox MLutyens.Mktg on 
SystemA. 
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add_mail_table_entry 



add_volume_registration 



To add an entry for a mailing list, you must use -mis instead of the address 
argument: 

add_mai l_table_entry mix -mis mixed_1ist 
ACCESS REQUIRED 

You must have e access to the gate mail_table_priv_. 



Name: add volume registration, avr 

SYNTAX AS A COMMAND 
I avr -control_args 
FUNCTION 

registers a new physical volume. If the specified logical volume does not exist, it is 
registered as well. 

CONTROL ARGUMENTS 

The following control arguments pertain to the registration of a physical volume. 

I -device.model N, -model N 

specifies the Honeywell model number for the disk device. The following values 
are valid for N: 

VALUE DEVICE 

kOO MSU0400 

kOl MSU0402 

i»51 MSUOifSl 

500 HSUO5OO 

501 MSUO3OI 
I 3380 MSU338O 
I 3381 MSU3381 

(Required) 
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add_volume_registration 



add_voliime_registration 



-location STR, -loc STR 

specifies the current location of the disk pack. This is for administrative 

information only. STR can be any 32 characters (e.g.. "offline — in cabinet 13"). 
(Default "uninitialized") 

-logicaLvolume LVNAME. -Iv LV_NAME 

specifies the logical volume name. If the given logical volume is not already 
registered on the system, you are queried if the new logical volume should be 
registered. (Required) 
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admin_mode_exit 



admin^util 



Name: admin^mode.exit, ame 
SYNTAX AS A COMMAND 
ame 

FUNCTION 

returns to initializer command level from admin mode. 



Name: admin util 

SYNTAX AS A COMMAND 
admin_uti1 {args} 
FUNCTION 

sets and prints values in the segment sys_admin_data in the working directory. This 
segment is normally kept in >udd>SysAdmin>lib (with a link to it in 
>udd>SysAdmin>admin). It contains a numb^ of values used by system administraticm 
procedures. One of these values is a lock, which prevents two system administrators 
from modifying the system administration databases simultaneously. This command also 
sets several values in the header of the administrator's copy of the SAT (smf.cur.sat. 
in the working directory). You can use the print^sat conmiand to print information in 
either >scl>sat or >udd>SysAmin>admin>smf.cur.sat 

ARGUMENTS 

lock wait„time 

attempts to lock the lock in sys^admin.data. If the lock is already locked (by 
another process) and remains locked for more than the specified wait_time (in 
seconds), then an error message is printed and the program_interrupt condition is 
signaled. (Default 60) 

print 

prints all values in sys_admin^data. 

set key value, default key value, dft key value 

sets the variabls indicated by key to the gives value. Since some of the settable 
variables are default values of project parameters, used when a new project is 
created, the words "default** and '*dft** are accepted as synonyms for '*set" The 
keys correspond to three classes of variables: installation-dependent items, project 
parameters, and the SAT header. 
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admin.util 



admin_util 



unlock 

attempts to unlock the lock in sys_admin_data. If the lock was not locked by the 
process that is executing the command, an error message is printed. If it was 
locked by an existing process (other than the one executing the command), it is 
not unlocked. 

UST OF INSTALLATION-DEPENDENT VARIABLES 

The following variables contain installation-dependent items that are printed on 
monthly bills and other administrative documents. Enclose the values of these items in 
quotes if they contain any blanks or other special characters. 

I user_accts XX, user_accts_office XX 

where XX is the official name of the office responsible for Multics billing, for 
example: "Fiscal Office" or "Accounting Department" It is the first line of a 
return address printed on bills by the mailing_page_ subroutine. It can be up to 
64 characters long. 

user_accts_addr XX 

where XX is the address of the above office, for example, a building and room 
number or a mail station. It is the second line of a return address printed on 
bills. It can be up to 64 characters long. 

user_accts_phone XX 

where XX is the phone number of the above office. It is also printed on bills. 
It can be up to 16 characters long. 

bl XX, b2 XX, b3 XX 

where XX strings, each of which can be up to 10 characters long, are printed in 
large letters by the mailing_page_ subroutine, as a set, below and to the left of 
the address of the bill recipient For example, 

INTER 

DEPARTMENT 
MAIL 



LIST OF PROJECT PARAMETER VARIABLES 

The following variables contain default values for several project parameters. They are 
used by the new_proj command when the accounting administrator does not specify 
values for these parameters. 
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admin_util 



attributes XX 

where XX, enclosed in quotes if it contains any blanks, must be acceptable to the 
parse_attributes_ subroutine. This string sets the default attributes for a new 
project The anonymous (anon) attribute, which allows anonymous users to be 
registered on a project, can only be assigned by a system administrator. For a 
more detailed description of registration of anonymous users done by the Project 
administrator see the Multics Project Administrator's manual {AK51). The other 
attributes can be assigned by a project administrator if the system administrator 
has set them for his project For convenience, all the valid attributes are listed 
below. 



administrator 


no_pr imary 


nopreempt 


admin 


no^pr i me 








epilog In 


anonymous 


no_secondary 


daemon 


anon 


no_sec 








preempt I ng 


brief 


no_start_up 


bumping 


dial ok 


no_warning 


save_pd I r 


dial 


nowarn 








save_on_d i sconnect 


disconnect_ok 


nobump 


save 


guaranteed^,] og I n 


nollst 


v_home__d I r 


guar 




vhomed i r 




none 




I group 


nul 1 


v_process_overseer 






villi bpl %/v> 


mul tI_login 






mu 1 t I p 







audit XX 

where XX is the default audit flags to be used when new projects are created or 

new users registered. For a description of the audit flags see the new_user 
conunand. 

grace N 

where N is the default grace time (in minutes) for a new project The grace time 
specified by N is the length of time primary users retain their primary status 
(protected from preemption). (Default 2880 minutes or 48 hours, which really 
means "never to be subject to preemption") 

group XX 

where XX identifies the default load control group for new projects. It can be 
up to eight characters long. (Default "Other") 

imt_ring N 

where the ring number specified by N must be a single digit from 1 to 7, 
inclusive. This is the defatdt initial ring for new projects. (Default 4) 
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admin^util 



inax_ring N 

where the ring number specified by N is the default max_ring for new projects. 
(Default: 5) 

LIST OF SAT HEADER VARIABLES 

The following variables are in the header of the SAT. 

uwt weight XX 

is the load control weight for the corresponding process overseer named XX, 
which can be up to 64 characters long. The weight must be an integer, equal to 
10 times the actual weight For example, users with the standard process overseer 
(process_overseer_) have a weight of 1, which is expressed as 10; users who have 
a process overseer that restricts them to an edit-only environment (for example, 
clerical personnel engaged in typing tasks) might have a weight of 0.5, which is 
expressed as S. The default value of uwt depends on the process overseer, for 
example: 



Weight Overseer 

10 process_overseer_ 

10 >system_l ibrary_too1 s>iod_overseer__ 

10 >systein_l ibrary_tool s>card_overseer 

5 >l imi ted_servi ce__system 



You can give the word "delete" (dl) instead of weight to delete the process 
overseer XX from the list The maximum number of unit weight table entries is 
24. 

administrator! User_id 

administrator2 User_id 

These two items are the User^ids of two persons who are permitted to act as 
system administrators. They may be specific people or, more general, User.ids. 
For example, 

JBSmi th.* 
*.Sys Admin 

permits anyone on the SysAdmin project, plus JBSmith when logged in on any 
project, to act as a system administrator. 
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admin_util 



adopt_seg 



max_units N 

The N is the load limit, which is 10 limes the actual user weights. For example, 
if the system can handle 80 users of weight 1, the N should be 800. The default 
value of max_units is 750. 

This limit is usually overridden by the per-shift values from the configuration 
table in the installation_parms segment. However, when automatic load control is 
disabled (in a special session, for example), the max_units figure in the SAT 
header is used. 



Name: adopt seg 

SYNTAX AS A COMMAND 
adopt_seg pvname vtocx path 

FUNCTION 

reconstructs a directory branch for a segment or directory whose branch has been lost 
but whose VTOCE exists. Individual segments may be adopted by the use of the 
adopt_seg command. 

ARGUMENTS 

pvname 

is the physical volume name of a mounted physical volume, on which the VTOCE 
for a branch that is to be constructed exists. 

vtocx 

is the VTOC index, in octal, of that VTOCE. 

path 

is the pathname of the entry lo be constructed for the segment or directory. The 
directory portion of this pathname must specify an existent directory. 

ACCESS REQUIRED 

Use of the adopt_seg command requires access to the phcs_ and hc_backup_ gates. 
NOTES 

Segments whose branches are to be constructed by adopt_seg can only be returned to 
their original position in the hierarchy; the superior directory must exist. 
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adopi_seg 



alarm_clock_meters 



The new branch that is created is lacking certain attributes, these attributes can be 
reconstructed either manually or by use of the rebuild_dir command. Default values 
are supplied for the following attributes: 



The fix_quota_used command and exec_com have to be used on directories that adopt 
segments in this way to correct quota used totals. This is always necessary if quota 
has been corrected since the branch was first lost. 



Name: alarm clock meters 

SYNTAX AS A COMMAND 

a 1 arm_c I ock_meter s {-contro 1_arg} 

FUNCTION 

displays information about the behavior of the simulated alarm clock used within the 
Multics system. 

CONTROL ARGUMENTS 

-report_reset. -rr 

generates a report and then performs the reset operation. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 

the last call with -reset specified. If -reset has never been given in a process, it 
is equivalent to having been specified at process initialization time. 

ACCESS REQUIRED 

This command requires access to phcs_ or metering_gate_. 



If the alarm_clock_meters command is given with no control argument, it prints a full 
report. 



name 

ring brackets 
safety switch 
copy switch 
access class 
bit count 
TPD switch 



ACL 



nul 1 

entry portion of path 
validation level of caller 
off 
off 

from VTOCE 

3685^"Current length as determined from VTOCE 



off 



NOTES 
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alarm_clock_meters 



The following are brief descriptions of the variables printed out by alarm_clock_meters. 

No. alarm clock sims 

is the total number of times that an alarm clock wakeup was generated. 

Simulation lag 

is the average value of the simulated clock delays (i.e., the time difference 

between when the alarm should have gone off and when it was actually 
processed). 

Max. lag 

is the largest of the simulated delays that has occurred since the time of 
bootload. This value is not affected by the -reset control argument 

Priority boosts 

is the number of times the alarm clock went off indicating a priority scheduling 
process on the ready list should be granted high priority, i.e., have its waiting 
time before rescheduling set to 0. This variable is not printed if zero. 

Priority elig. lost 

is the number of times the alarm clock went off indicating a priority process that 
had been running lost its eligibility because it had used up its eligible time. This 
variable is not printed if zero. 



EXAMPLES 

The following is an example of the information printed when the alarm_clock_meters 
command is invoked with no control argument 

Total metering time 1:36:35 

No. alarm clock sims. 227^ 

Simulation lag 91.676 msecs. 

Max. lag 2305 •883 msecs. 

Priority boosts 6 
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Name analyze multics, azm 

SYNTAX AS A COMMAND 
azm {-control_args} 
FUNCT/ON 

invokes a subsystem that aids in system crash analysis. It can analyze dumps created 
I by the bootload command environment (BCE) dump command and copied into >dumps 
I in the Multics hierarchy by the copy.dump command. It can also analyze processes 

saved by the answering service after a fatal process error and copied by the 

copy.deadproc command. 

CONTROL ARGUMENTS 

-abbrev, -ab 

enables abbreviation expansion of request lines. 

-no_abbrev, -nab 

does not enable abbreviation expansion of request lines. This is the default 
-no_prompt 

suppress^ the prompt for request lines in the request loop. 

-no_start_up, -nsu 

does not execute any startup exec.com. This is the default. 

-profile PATH, -pf PATH 

specifies the pathname of the profile to use for abbreviation expansion. The 
suffix "profile" is added if necessary. This control argument implies -abbrev. 

-prompt STR 

sets the request loop prompt to STR. The default is the ioa_ STR: 
'^/azm'^[ (M)'^]:^2x 

-request STR, -rq STR 

executes STR as an azm request line before entering the request loop. 

-start_up, -su 

executes the exec_com "start.up.azmec" upon invocation of azm. This start_up 
exec_com is first searched for in your home directory, then in your project 
directory (>udd>ProjectJd). and last in >site. The first exec.com found is used. 

-quit 

exits azm after execution of other argum^ls. Can be used with -request 
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anaiyze_muliics analyze_multics 



NOTES 

This command uses the standard search iisl mechanism lo locale dumps. If il does not [ 
find a "dumps" search list, it creates one, placing >dumps and >dumps>SAVE_pdrs in | 
the search list as the default. If additional search paths are desired, the add_search_path 
command can be used to define them. 

VIRTUAL ADDRESS CONSTRUCTS 

Accessing data requires some pointer value to define an address space. The generation 

of the pointer value is performed b}- resolving a virtual address (virtual-addr). A 

virtual-addr consists of two parts: a segment number and a word offset. 

The command resolves virtual-addrs from the following types of information: 

Symbol: 

is a symbolic name for a segment number and an offset that can be resolved by 
data in definitions_ (i.e.. sstSptl can be resolved to the correct segment num.ber 
and offset of the page table lock). 

Segment name: 

a segment name can be resolved in many ways, but it can only provide one part 
of the virtual address: azm uses 0 as the default offset for this pointer value 
(i.e.. tc_data is resolved to SEGNO |0). 

Segment number: 

a segment number needs no resolution, but a default action needs to be taken for 
the offset (the default is 0. i.e.. SEGNO iO). 

Segment name/ number and offset: 

the virtual-addr in this case can be a segment name or segment number and an 
octal offset (i.e.. the construct of pds|20 is translated to SEGNO] 20 or dseg|5 is 
0 1 5). The notation " i " and "$" must be used without spaces (e.g.. 244 1 0 or 
sstScmp). 

Temporary pointers: 

azm keeps a set of 11 temporary pointers per translation. (See the set request for | 
a list of these pointers.) A translation is one complete entity such as a "dump". | 
These pointers can be set with the set request (e.g.. set sp 230 1 100). They can be | 
referenced by other requests as another type of "symbol" in a virtual-addr 
expression, after they have been set. If not set. these pointers are null. 

Offset operators: 

the operators "+N" and "-N" immediately preceding an octal number or 
virtual-addr construct can be used to alter the offset of a virtual address. N is a 
number interpreted in octal. No spaces are allowed between the operator and the 
N. For example. sstSptl +30 are resolved to be the SEGNO for sst_seg with the 
offset of ptl plus 30 octal locations; sst$ptl+30 is also valid. 
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Indirection: 

a vinual-addr can imply indireciion. The indirect word can be used as an ITS 
pair if it is a valid ITS word pair; if not. the upper half of the word is used. 
The following virtual-addr construct is used to specify indirection (sstScmp,*). The 
format of an indirect pointer value is: 

segno j of f set , " segname jof f set , " symbol," 
Lemp_ptr,'f temp_ptr [offset, - 

EXAMPLES OF INDIRECTION 

17|230,5't sst|230,''' sst$cmp,i'«+2 
sp,>'j sp|230," 

LIST OF REQUESTS 

absolute address, absadr 

SYNTAX 

absadr virtual-addr 

SYNTAX AS AN ACTIVE REQUEST 

[absadr virtual-addr] 

FUNCTION 

translates a "virtual address" to an absolute memory address. 

ARGUMENTS 

virtual-addr 

can be a segment number, name, or symbolic address (e.g., 64, prds, prds$am_data). 
See "Virtual Address Constructs" above. 

ACTIVE REQUEST EXAMPLE 

! d i spl ay_absol ute [absadr sst$cmp] 2 

displays the first two words of the absolute address of sst$cmp. 
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add request table, arqt 

SYNTAX 
arqt path 
FUNCTION 

adds a user-defined request table in the list of request tables being searched by the 
current azm invocation. 

ARGUMENTS 

path 

is the pathname of the request table to be added. This request table must be 

consistent for use with the subsystem utility. (Refer to the Mufti cs Programmer's 
Reference Manual, Order No. AG91. for request table structure.) 



apply, ap 

SYNTAX 

ap virtual-addr {range} command_line 
FUNCTION 

extracts all or part of a segment specified by VIRTUAL-ADDR from the selected 
dump, and places a copy in a temporary segment. This pathname is passed as the last 
argument in the command_line. 

ARGUMENTS 

virtual-addr 

may be a segment number, name or symbolic address (e.g.. 64, prds, prds$am_data). 
See "Virtual Address Constructs" above. 

range 

specifies the number of words in octal to be copied. The default is the entire 
segment. 

command_line 

is any command. 
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NOTES 

The offset in the virtual address specifies where the copying of the segment begins. 
When only part of a segment is extracted, it goes at the beginning of the temporary 
segment. For example: 

ap pds$ain_data kOO dump_segment 
puts 256 (decimal) words at the beginning of the segment. 



apte 

SYNTAX 

apte {proc_i nd i cater} {-control_args} 
FUNCTION 

I displays active page table entry (APTE) information for processes in a dump whose 
j states match the states specified. 

I ARGUMENTS 

I proc_indicator 

i used for specifying individual processes. It can take one of three forms: 

j - The decimal index (starting at zero) of a process in 
I the dump. 

I - The octal APTE offset of the process, 

j - The octal process_id of the process. 

I CONTROL ARGUMENTS 

I -all -a 

j displays APTE information for all processes in any state. This is the default, 

j -blocked, -blk 

I displays APTE information for all processes in the blocked state. 

I -count, -ct 

I specifies the total number of processes meeting the criteria specified by 
j controLargs. With -all, it gives the counts of each process state. 

I -current, -cur 

I displays APTE information for the current process. 

I -page_tbl_lock, -ptl 

I displays APTE information for all processes marked as page table locking. 
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-ready, -rdy 

displays APTE information for all processes in the ready state. 

-run 

displays APTE information for all processes in the running state, 
-stopped, -stop 

displays APTE information for all processes in the stopped state, 
-wail 

displays APTE information for all processes in the waiting state. 
EXAMPLES 
apte 2 

displays information for process 2 in a dump, 
apte 10600 

displays information for the process with APTE offset 10600 (octal). 

apte 3500555555 
displays information for the process with octal process_id 003500555555. 

associative memory, am 

SYNTAX 

am {-control_args} 

FUNCTION 

displays SDW and /or PTW a^ociative memori^. 

LOCATION CONTROL ARGUMENTS 

-dump 

displays the "dump" associative memories from the bootload CPU at the time the 
dump was taken. This is the default. 

-prds 

displays associative memories that have been stored in the prds of the processor 
on which the current process is running. 
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CONTROL ARGUMENTS 
-all. -a 

displays all entries in the associative memories. The default is to display only 
those entries that are valid (i.e., the full bit is on). 

-ptw 

displays only the PTW associative memories, 
-pageno PAGENO 

displays only those entries in the PTW associative memories that have a page 
number that matches the value of PAGENO (which is an ocul page number). 

-sdw 

displays only the SDW associative memories, 
-segno SEGNO 

displays only those entries in the SDW and PTW associative memories that have a 
segment number that matches the value of SEGNO, which is an octal segment 
number. (See assoc_mem.incl.pll.) 

NOTES 

If no control arguments are given, both the SDW^ and PTW associative memories are 
displayed for the "dump" associative memories. 



aste 

SYNTAX 

aste segno/segname {-contro l_args} 
FUNCTION 

displays active segment table (AST), page table, and trailer information. The default 
displays active segment table entry (ASTE) and page table information only. 

ARGUMENTS 

segno/segname 

is the segment number or segment name of interest. 

CONTROL ARGUMENTS 

-aste 

displays AST information for the selected entry. 

-at offset, -at virtual -addr 

displays ASTE information starting at the offset or virtual address specified. 
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-brief, -bf 

displays everything excluding the page table information, 
-long, -Ig 

displays everything, that is. the ASTE, page table, and trailer information. 

-page_table. -pt 

displays page table information for the selected segment. 

-trailer, -tr 

displays trailer information about the selected segment. 



configuration deck, cd 

SYNTAX 

cd {carcl_names} {-control_args} 

FUNCTION 

displays the contents of the configuration deck m the selected dump. This request 
works exactly like the standard pcd command, except that it gets the configuration 
deck from the dump. 

ARGUMENTS 

card_names 

are the names of the particular configuration cards to be displayed. Up to 32 
card names can be specified (separated by spaces). If no card names are given, 
the complete configuration deck is printed. 

CONTROL ARGUMENTS 

-brief, -bf 

suppresses the error message when a requested card name is not found. This is 
the default. 

-exclude F1ELD_SPECIFIERS, -ex FIELD.SPECIFIERS 

excludes particular cards or card types from being displayed. One to 14 field 
specifiers can be supplied with each -exclude, and up to 16 -exclude control 
arguments can be specified. To be eligible for exclusion, a card must contain 
fields that match all field specifiers supplied with any -exclude argument. 

-long. -Ig 

prints an error message when a requested card name is not found. 
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-match F1ELD_SPECIFIERS 

selects particular cards or card types to be displayed. One to 14 field specifiers 
can be supplied with each -match, and up to 16 -match control arguments can be 
specified. To be eligible for selection, a card must contain fields that match all 
field specifiers supplied with any -match argument. 

NOTES 

Field specifiers can consist of a complete card field or a partial field and an asterisk 
(*). An asterisk matches any part of any field. Specifiers for numeric fields can be 
given in octal or decimal, but if decimal the}' must contain a decimal point. Asterisks 
cannot be specified in numeric field specifiers. All numeric field specifiers are 
converted to decimal and matched against numeric card fields, which are also 
converted to decimal. Hence, the field specifier "1024." matches a card containing the 
octal field 2000. and the field specifier "1000" matches a card containing the decimal 
field 512. Note that all card names must be specified before the first -match or 
-exclude argument. Field specifiers following a -match or -exclude argument include 
all arguments until the next -match or -exclude argument. 



display, d 
SYNTAX 

d virtual-addr {exp} {range} {-contro 1 _args} 

SYNTAX AS AN ACTIVE REQUEST 

[d virtual-addr {exp} {range} {-control_args} ] 

FUNCTION 

displays a selected portion of a segment in a dump or a saved process. 

ARGUMENTS 

virtual-addr 

specifies the initial offset of the virtual address space to be dumped. May be a 
segment number, name, or symbolic address (e.g., 64. prds, prds$am_data). See 
"Virtual Address Constructs" above. 

exp 

is an expression, which is either an octal value or a virtual-addr construct yielding 
an octal value. This value can be positive or negative, specified by the plus or 
minus sign. 

range 

specifies the number of words to be dumped in octal. If a range is not specified, 
the default action is to display one word. If the data is an ITS pair, two words 
are displayed. 
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MODE SPECIFICATION CONTROL ARGUMENTS 

-character, -ch, -ascii 

displays the selected number of characters in ASCII. Characters that cannot be 
printed are represented as periods. As an active request, -character returns the 
character representation of the requested address. 

-instruction, -inst 

displays the selected number of words as instructions. Read-only segments that are 
not part of the dump are located using the hardcore search paths. The default 
directory for hardcore search paths is >ldd>hard>e. However, sites that have 
modified hardcore can place the directory containing modified bound segments 
before >ldd>hard>e in their hardcore search paths. Usage as an active request is 
not allowed. 

-octal, -oc 

displays the selected number of characters in octal. When used as an active 
request, it returns the octal value of the requested address. This is the default 

-ptr. -p 

displays the selected number of word pairs as pointers. When used as an active 
request, it returns the octal value in the form SEGNO | OFFSET. 

-pptr. -pp 

displays the selected number of words as a packed pointer. When used as an 
active request, it returns the octal value in the form SEGNO | OFFSET. 

-pptrx, -ppx 

displays the selected number of words as packed pointers and expands me 
SEGNO I OFFSET to a segment name. Usage as an active request is not allowed. 

-ptrx, -px 

displays the selected number of word pairs as pointers and expands the 
SEGNO I OFFSET to a segment name. Usage as an active request is not allowed. 

CONTROL ARGUMENTS 

-as STRUCTURE_NAME 

displays the data as a PL/I structure defined by STRUCTURE^NAME. The 
STRUCTURE_NAME is an inner ring system-defined include file. See the info 
file structure_name.info for a list of available structures and their short names. 
The address given in the display request is taken as the address of the beginning 
of the structure. If the whole structure is being displayed, that is the address 
where display begins. If only certain elements are being displayed, that is the 
address used to compute offsets of the elements. The structure reference following 
-as must be a single string, containing no spaces, and must follow the syntax 
described below. The single string is used to specify structure elements, array 
indexes, and substring matching. Usage as an active request is not allowed. 
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-long, -ig 

displays each element of the structure on a separate line. This control argument is 
only implemented with -as. 

STRUCTURE SYNTAX 

The structure reference is made up of two parts: a structure element reference and an 
optional set of match strings. If no match strings are supplied, no string matching is 
done. The structure element reference syntax consists of one or more element names, 
separated by periods, and may contain subscripts following some of these element 
names. The first name in a structure element reference must be a level-one structure 
reference; partially qualified top-level references are not permitted. Intermediate levels 
of qualification may be omitted as long as there is no ambiguity. 

All subscripts must be supplied as decimal integers. The subscripts can be cross-section 
references such as *'(1:4)" to reference elements one through four. Asterisk bounds 
cannot be used: if a cross section is desired, its upper and lower bounds must be 
given as decimal constants. If an element has more subscripts than are supplied, the 
complete cross section is printed for the remaining subscripts. To eliminate the need 
for quoting, subscripts may be surrounded by braces instead of parentheses. 

To specify that only certain elements be displayed (such as all those with names 
containing the string "time"), a set of match strings can be given after the structure 
element reference. Each match string b^ins with a slash and is followed by the string 
itself. The final match string can be followed by a slash, but this is not required. If 
match strings are specified, any element that matches at least one string is displayed. 

EXAMPLES OF STRUCTURE REFERENCES 

pvt 

the whole structure "pvt". 
pvLn_entries 

the single element "n_entries" in the structure "pvt". 
sst/time/, sst/time 

any elements in the structure "sst" containing the string "time". Note that the 
final slash is optional. 

sst/ time/meter/ 

any elements in the structure "sst" containing either the string "time" or the string 
"meter". 

sstspace{3} 

element three of "sstspace". 
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ssLspace {2:4} 

elements two, three, and four of ^'sstspace**. 

ssLspace 

all elements of "ssLspace". 

ssLleveHl} 

both elements of the "level" array for "ssLlevel {1} " 
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ssLlevel {1} .ausedp. ssLlevel.ausedp { 1] 

the single element "ausedp" of the "level" array for "ssLlevel {1} " 

STRUCTURE OUTPUT FORMAT 

The default output format is a compressed form, which places as many values on a 
line as will fit within the line length. The -long control argument places one value on 
a line. The short form, additionally, collects all bit(l) flags and displays them, at the 
end of the display for each substructure or array element, in two groups: one listing 
all the flags that were on ("r'b) and one for all the ones that were off ("0"b). 

All PL/ 1 data types are displayed in the same representations used by probe. 
Additionally, the following special formats are used: 

1. Bit strings are displayed in octal if the length is divisible by three, in hex if 
divisible by four, and as bit strings otherwise. 

2. Character strings are displayed as a string concatenated with a repeated constant if 
the string is padded on the right with more than 16 nulls, spaces, or octal 777 
characters. 

3. Large-precision (> 51) fixed binary values are also displayed as clock readings if 
their values represent clock readings within 10 years of the present. 

DISPLAY REQUEST EXAMPLES 



d 75|560 2 

displays the two words in seg number 75 starting at offset 560. 
d pds|560 2 

displays the two words in the segment named pds starting at offset 560. 
d pds$trace 

displays one word in the pds segment beginning at the offset specified by $trace. 

display 2l+^|260 +20 k 
displays four words of segment number 244 starting at offset 300 octal. 

d sp 20 

displays 20 octal words starting with the segment offset defined in the azm internal 
temporary pointer (see set request). 
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d sst$cmp,'t +sst$cmesi2e sstSstrsize 

causes the word at sst$cmp to be used as an indirect word, or an indirect pointer if 
the resultant address has ITS modification, to develop the starting virtual address. The 
value derived from sst$cmesize is then added to the starting offset for the "final" 
starting address. The range, or number of words to be displayed, is specified by the 
value contained in sstSstrsize. 

d sst|2 -as apte 

displays the APTE entry at the given offset in the SST as it is defined by 
apte.incl.pll. 



display absolute, da 

SYNTAX 

da abs-addr {range} {-control_args} 

SYNTAX AS AN ACTIVE REQUEST 

[da abs-addr {range} {-control_args} ] 

FUNCTION 

dumps an absolute memory address space in the dump. 

ARGUMENTS 

abs-addr 

is the starting absolute memory address, in octal, 
range 

specifies the number of words to be dumped in octal. If a range is not specified, 
the default is one word. If the data to be dumped is an ITS pair, two words are 
dumped. 

MODE SPECIFICATION CONTROL ARGUMENTS 

For a description of the mode specifications, see the display request. 

-character, -ch, -ascii 

-instruction, -Inst 

-octa 1 , -oc 

-ptr, -p 

-pptr, -pp 

-pptrx, -ppx 

-ptrx, -px 
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events, ev 

SYNTAX 

ev {-contro1_args} 
FUNCTION 

displays significant events, in reverse clironological order, from a dump (see "Notes"). 
CONTROL ARGUMENTS 
-last N, -It N 

specifies the number of events to print. The default is to print 10 events. j 

-long. -Ig 

displays disk queue events. 

-time NSECS. -tm NSECS 

specifies the time in seconds before the dump was taken vv'hen events were 
significant. The default is 10 seconds. 

NOTES 

The following events are considered as significant: machine conditions (from BCE, j 

prds, pds, and the mc_trace_buf). traffic control state change time, system error j 

messages, Fim frames in any stack, and connects by device and disk queues (long | 

report only). If neither -time nor -last are specified, the default action is equivalent j 

to "ev -time 10". i 



history regs, hregs 

SYNTAX 

hregs {hregs_spec i f i er} {-control_args} 
FUNCTION 

displays a composite analysis or octal dump of the processor history registers. This 
request is useful for people who are knowledgable of the hardware. The default action 
is to display the AU, CU, DU, and OU history registers for the pds in a threaded 
order and interpreted format. 
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ARGUMENTS 

hregs_specifier 

may be chosen from the following: 

-condition virtual-addr. -cond virtual-addr 

displays history registers from a condition frame, the location of which is 
described by virtual-addr. 

-dump 

displays the "dump" history registers from the bootload CPU at the time the 
dump was taken. 

-pds 

displays the history registers that have been stored in the current processes 
pds. This is the default. 

virtual-addr 

displays the history registers that have been stored at the address space 
specified by virtual-addr. 

CONTROL ARGUMENTS 

-au 

displays the AU history registers only. 

-cu 

displays the CU history registers only. 

-du 

displays the DU histor}' registers only. 

-ou 

specifies that only the OU history registers are to be displayed, 
-interpret 

displays the interpreted form of the history registers only (default), or. if -octal 
is given, includes the octal representation also. 

-octal, -oc 

displays the octal values of history registers only, or, if -interpret is also selected, 
displays octal and interpreted form. If neither -octal nor -interpret is specified, 
the default action is to display the interpreted form only. 

-thread 

displays the selected history registers in the "correct" order. This is the default. 

-no_thread 

displays the selected history registers in serial order, without attempting to sort 
them. 



2-28 



GB64-00 



analyze_multics analyze_multics 



iist dumps, Isd 

SYNTAX ' 

Isd {path} {-contro1_args} j 
FUNCTION 

lists the dumps and /or the dead processes in the selected dump directory. If path is j 

not given, it lists all dumps and/or dead processes in the dump directories specified | 

in the dumps search list. | 

ARGUMENTS 

path 

is the pathname of the dump directory to be checked. Starnames are acceptable. i 

CONTROL ARGUMENTS j 

-deadproc, -dp i 

specifies that only dead processes are to be listed. If path is not given, it checks i 

all dump directories specified in the dumps search list for dead processes. i 

-fdump. -fd I 

specifies that only dumps are to be listed. If path is not given, it checks all j 

dump directories specified in the dumps search list for dumps. This is the i 

default. I 

NOTES I 

If no arguments are given, the default is to list only dumps. i 

Analyze_multics will use the search_iist_defaults_ mechanism to locate and set up the i 

dumps search list, which, by default, will contain the directories >dumps and i 

>dumps>save_pdirs. i 



list processes, Isp 

SYNTAX 

Isp {proc_i nd i cater} {-contro l_args} 

SYNTAX AS AN ACTIVE REQUEST 

[Isp {proc_i nd i cater} {-control_args} ] 
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FUNCTION 

lists all known processes in the selected dump. As an active request, it returns the 
I process_ids meeting the control argument criteria, otherwise it returns a null string. If 
I -count is specified only the total is returned. 

ARGUMENTS 

proc_indicator 

used for specifying individual processes. It can take one of three forms: 

- The decimal index (starting at zero) of a process 
in the dump. 

- The octal ARTE offset of the process. 

- The octal process_id of the process. 



CONTROL ARGUMENTS 
-all, -a 

lists all processes in the dump. This is the default. 

-blocked, -blk 

lists processes marked as blocked. 

-count, -ct 

counts all processes. With -all. it gives the counts of each process state. 

-current, -cur 

lists the current process. 

~page_tbl_lock, -ptl 

lists processes marked as page table locking. 

-ready, -rdy 

lists processes marked as ready. 

-run 

lists processes marked as running. 

-stopped, -stop 

lists processes marked as stopped. 

-wait 

lists processes marked as waiting. 
EXAMPLES 

! do "sel ect_process &l;sdw 0" ([1 i st_processes]) 
displays the SDW for DSEG for all processes in the dump. 
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machine conditions, mc 

SYNTAX 

mc {mc_spec i f i er] {-control_args} 
FUNCTION 

displays all or parts of machine conditions based on the given pointer. 

ARGUMENTS 

mc_specifier 

may be chosen from the following: 

-dump 

specifies the dump for the bootload CPU registers at the time of the dump. | 

-pds {STRl} I 

where STRl can be "all", "fim" ("fim_data"), "page_fault" ("pgf", | 

"page_fault_data"), "signaller" ("signal", "sig". "signal_data"). It defaults to | 
"all" if STRl is not given. 

-prds {STR2} 

where STR2 can be "all", "fim" ("fim_data"), "interrupt" ("int", "interrupt_data"). j 

"system_trouble" ("sys". "sys_trouble_data"). It defaults to "all" if STR2 is not | 

given. I 

virtual-addr 

is the virtual address construct used to define the address space containing 
machine conditions. 

The virtual address can point directly to the machine conditions or to the | 
frame that contains the machine conditions. In the latter case, the offset is | 
calculated for the user. ] 

CONTROL ARGUMENTS 

-eis 

displays the EIS pointers and lengths (interpreted). 

-faults, -fit 

displays the fault register. 

-long, -Ig 

displays all elements of the MC. 

-mc_err 

displays the mc_err data word. 
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-misc 

displays the miscellaneous data (i.e.. mc_err, fault reg, time), 
-octal, -oc 

displays the eis info, SCU data, or pointer registers, in octal. This control 
argument is used with -scu, -eis, or -regs. 

-pointers {PR_LIST} . -prs {PR.LIST} 

displays pointer registers selected by PR_LIST (from 0 to 7, separated by spaces). 
If PR_LIST is not specified, all the pointers are displayed. 

-ppr 

displays only the PSR and IC from the MC. 

-registers {REG_LIST}, -regs {REG_LIST} 

displays only the basic OU registers. REG_LIST can be any of the following: 

xO xl x2 x3 x^ x5 x6 x7 a q all. 
If REG_LIST is not specified, all of the basic OU registers are displayed. 

-scu 

displays only the SCU data of the MC. 

-time, -im 

displays the MC time. 

-ipr 

displays only the TSR and the CA from the MC. 
NOTES 

If no MC specifiers are given, the temporary pointer prmc is used. The default 
* control arguments are -fault, -mc_err. -pointers, -scu, -time, and -tpr. The 
machine_conditions request sets all azm-defined temporary pointers as seen in the 
machine_condition frame. 

EXAMPLES 

mc -pds fim -scu 

displays the SCU data found in the fim frame of the PDS currently being referenced 
in the dump. 
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page trace, pgt 

SYNTAX 

pgt {-control_args} 

FUNCTION 

displays the contents of the page trace table in the current process data segment 
(PDS). The default is to display the last 15 trace entries. Trace entries are alwaj's 
displayed in reverse chronological order. 

CONTROL ARGUMENTS 

-all. -a 

displays all trace entries. 

-last N, -It N 

specifies the number of trace entries, where N is a positive decimal integer, to be 
displayed. 



replace, rp 
SYNTAX 

rp segno/segname path 

FUNCTION 

replaces the segment designated by segno/segname in the current translation table with 
another segment designated by path. 

ARGUMENTS 

segno/segname 

the segment number or segment name within the translation table to be replaced. 

path 

is the pathname of the segment. The equal convention can be used. For example: 
rp bound__sys tem_f aul ts [e wd]>=.new 



NOTES 

Both per-process and per-system segments can be replaced. For example, if the PDS 
is replaced in a process, it affects only the current process: whereas if tc_data is 
replaced in a process, it affects the whole dump. 
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scus 

SYNTAX 
scus 

FUNCTION 

prints the memory address space (in octal) of each SCU from the registers saved in 
I the dump. 

sdw 

SYNTAX 

sdw {segno/name} {segno/name} 

FUNCTION 

displays the SDWs in the current process' DSEG. 

ARGUMENTS 

segno /name 

is the segment number or name of interest. The first is the starting segment 
number and the second is the ending segment number. If only one is given, only 
one is displayed; if none are given, all are displayed. 

search, srh 

SYNTAX 

srh virtual-addr {range} search_str i ng 

SYNTAX AS AN ACTIVE REQUEST 

[srh virtual-addr {range} search_str i ng] 

FUNCTION 

searches a segment starting at virtual-addr matching on search_string. The search is 
performed on a 36-bit-word boundary. As an active request, the virtual addresses 
m.atching the criteria specified are returned. 

ARGUMENTS 

virtual-addr 

is the pointer to the address space to search. 
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range 

specifies the number of words to be searched from the starling offset, where 
range is an octal value. The default is the rest of segment. The search is started 
from virtual-addr. 

search_string 

is a 12-character string representing the 12 octal digits that make up a machine 
word (36 bits. 3 bits per digit). This forms both the search data and search mask 
by using the hyphen (-) as a "don"t care character" in the string. The "do care 
digits" are octal "from 0 to 7." Any other character is illegal. 

EXAMPLES 

To search for 

1. all words in segment 76 that have the last two digits of 43: 

srh 76 43 

2. all words in tc_data where the upper half = 070707: 

srh tc_data O70707 

3. words that end in 1234 in sst_seg starting at 1000, but only searching for 200 
octal words: 

srh sst_seg|1000 200 123^ 

4. words that start with 45 and end with 77, starting at sst_seg$ptl for 100 words: 

srh sst_seg$ptl 100 45 77 

segment name, name 

SYNTAX 

name arguments 

SYNTAX AS AN ACTIVE REQUEST 

[name arguments] 

FUNCTION 

prints the segment name given either a virtual address or a segment number. 
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ARGUMENTS 
virtual-addr 

is the virtual address construct used to define the segment. 

number 

is the segment number of the segment to be referenced. Thus, "name 230" returns 
j the name associated with the segment number 230, which (in MRll.O) is "stack_0". 

segment number, number 

SYNTAX 

number arguments 

SYNTAX AS AN ACTIVE REQUEST 

[number arguments] 

FUNCTION 

prints the segment number given either a virtual address or a segment name. 

ARGUMENTS 

virtual-addr 

is the virtual address construct used to define the segment, 
name 

is the name of a segment, e.g., stack_0. Thus, "number sst_seg" returns the 
j segment number associated with the segment sst_seg. 

! 

I select deadproc. sldp 

j SYNTAX 

I sldp {name} 

} FUNCTION 

j selects and translates a dead process which has been copied into the Multics hierarchy 

I via the copy_deadproc tool. The dead process is located by means of the dumps 

I search list. By default, copied dead processes are found in >dumps>save_pdirs. 
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ARGUMENTS 
name 

is the pathname of the process directory of interest. This can be a relative or 
absolute pathname. The dead process directory name is of the form person.pdir 
or person.N.pdir. where N is a numeric number. N=l for the most recently 
copied dead process. The suffix "pdir" is assumed if not given. 

NOTES 

When sldp is invoked with no arguments, it prints an identifying message. 



select dump, sld 

SYNTAX 

sld {name} {-control_args} 

FUNCTION 

selects and translates a dump of a system crash. The dump is found via the dumps 
search list. 

ARGUMENTS 

name 

is the ERF number or the pathname of the zero component of the dump. It can 
also be the form path>35. where 35 is the ERF number. Several control 
arguments are also acceptable if name is not specified. 

CONTROL ARGUMENTS 

-first, -ft 

selects the first dump (by ERF number) in the dump directory found via the 
dum.ps search list. 

-last, -It 

selects the last (most current) dump in the dump directory according to ERF 
number. 

-next, -nx 

selects the next dump in the dump directory. This is relative to the dump 
currently being looked at. 

-previous, -prev 

selects the previous dump in the dump directory. This is relative to the dump 
currently being looked at. 
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NOTES 

The sld command attempts to select the process as indicated by scs$trouble_processid. 
If this cannot be done, the default is the first running process found in the dump. 

select process, sip 

SYNTAX 

sip {proc_i ndi cater] {-control_args} 

FUNCTION 

selects a process for examination. When invoked with no arguments, the current 
process is listed. 

ARGUMENTS 

proc_indicator 

used for specifying individual processes. It can take one of three forms: 

- The decimal index (starting at zero) of a process in the dump. 

- The octal APTE offset of the process. 

- The octal process_!d of the process. 



CONTROL ARGUMENTS 
-brief, -bf 

suppresses the message about changing processes, 
-cpu TAG 

selects the DBR for the process running on the CPU identified by TAG (where 
TAG is one character in the range a through h). 

-dbr dbr_value 

selects the process defined by the dbr_value. 

-long, -Ig 

prints a message announcing the new process selected. This is the default. 
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set 

SYNTAX 

set ptr_n vi rtual -addr 
FUNCTION 

sets an internal temporary pointer like a CPU pointer register (i.e., "pr6" or "sp"). 
These pointers can then be used as a virtual-addr by other azm requests. 

ARGUMENTS 

ptr_n 

can be either the name or number of a "temporary pointer." 
There are eight temporary pointers and two special-case pointers: 



NUMBER 


NAME 


NUMBER 


NAME 


prO 


ap 


prk 


Ip 


prl 


ab 


pr5 


lb 


pr2 


bp 


pr6 


sp 


pr3 


bb 


pr7 


sb 



prmc intended to be a pointer to the current MCs. 

prfr intended to be a pointer to the current stack frame. 

virtual-addr 

can be a segment number, name, or symbolic address (e.g., 64. prds, prds$am_data). 
EXAMPLES 

set pr6 240 | 100 

sets a temporary ptr named pr6 (sp). 
set sb 2^0 

sets the temporary ptr (sb) to the base of seg 240 (240 10). 
NOTES 

The value of a temporary pointer can be displayed via the value request: 
V {ptrn I -all} 



2-39 



GB64-00 



ana]yze_muliics 



analyze_multics 



stack, sk 

SYNTAX 

sk V i r tua 1 -addr {-contro1_args} 

FUNCTION 

traces a given slack. 

ARGUMENTS 

virtual-addr 

is the virtual address construct defining the stack to be traced. 
CONTROL ARGUMENTS 
-arguments, -ag 

prints the arguments for the stack frames traced. Analyze_multics (azm) does not 
interpret the descriptors in an argument list passed lo an internal procedure 
declared options (variable) because azm has no knowledge about arguments for 
internal procedures. 

-for N 

traces for N stack frames. If no valid stack frames exist (stack_begin_plr = 
stack_end_ptr), a -force must be used. 

-force, -fc 

forces a forward stack trace. This should be used when there are no valid frames 
for this stack (siack_begin_ptr = stack_end_plr). 

-forward, -fwd 

traces in a forward manner. 

-long. -Ig 

prints the arguments and an octal dump of the stack frames traced. 

NOTES 

The default is to trace the stack in reverse order unless -force or -forward are 
specified. If the virtual-ADDR has a zero offset, then the trace starts at the offset 
of the first stack (stack_header.stack_begin_ptr). If it has a nonzero offset, then the 
trace starts from that offset in the given stack. 
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syserr log, siog 

SYNTAX 

slog {-control_args} 
FUNCTION 

displays all or parts of the syserr_log and syserr_data segments from the dump. It 
does not examine the perm_syserr_log. The default is to print the entire log. 

CONTROL ARGUMENTS 

-action A 

displays messages starting at action 0 to the action code specified by A. where A | 
is a decimal integer in the range 0 to 9. 

-exclude STR -ex STR 

excludes any message that contains STR. where STR is a string that is matched 
against messages in the log. 

-last N. -It N 

starts the scan N messages back from the end of the log. where N is a decimal 
integer. 

-match STR 

displays any message that contains STR, where STR is a string to be matched 

acrpiriQT mp<:<:pcyf><; in fhp Inp 

-expand, -exp 

interprets the binary data of messages. The format is generally dependent on the 
text of the message. 



traffic control queue, tcq 

SYNTAX 

tcq {-control_args} 
FUNCTION 

displays process DBR, process state, process ID, current CPU. and user ID from the 
traffic controller's eligible queue, as well as the "process number" in the dump. The 
default is to display only the eligible queue. 
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CONTROL ARGUMENTS 
-all 

displays the eligible, real-time, interactive, and work-class queue entries, including 
the unthreaded entries. 

-ready, -rdy 

displays the eligible, real-time, interactive, and work-class queues, excluding the 
unthreaded entries. 



value. V 

SYNTAX 

V ptr_n i . . . ptr_nn 

or 

V -a1 1 
FUNCTION 

displays the current value of one or all of the temporary pointers. 

ARGUMENTS 

ptr_n 

specifies which of the temporary pointers is to be displayed. Refer to the set 
request for a list of the azm-defined pointer names. 

-all, -a 

specifies that all of the pointers are to be displayed. This is the default. 

verify associative memory, vfam 

SYNTAX 

vfam {-control_args} 

SYNTAX AS AN ACTIVE REQUEST 

[vfam {-control_args} ] 

FUNCTION 

performs a consistency check on the associative memories stored at the time of a 
dump by comparing them to the appropriate entries in the "dump dseg" and page 
tables. When used as an active request, returns "true" if any inconsistencies are found, 

"false" otherwise. 
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CONTROL ARGUMENTS 

restricts the verification to the FTW associative memories, 
-sdw 

restricts the verification to the SDW associative memories. 
NOTES 

If you give no argument, both SDW and PTW associative memories are checked. 



why 

SYNTAX 

why 

FUNCT/ON 

tries to find the stack that has a call to syserr_real$syserr_real or calLbos$call_bos 
and sets the temporary pointers pr6 and prfr to the stack frame. This request searches 
the stacks for a frame that has a Tetum_to_ring_0_ frame and sets the temporary 
pointers from this set of machine conditions that called this entry. 

NOTES 

if the crash is due to fim_utii$check_fauit finding a problem, the machine condition 
CU data is displayed and all temporary pointers are set from these machine conditions. 
If this is an execute fault, then some lock info is printed and the process selected is 
lock ordered: sst_seg$ptl followed by sst_seg$aslt, then scs$connect_lock followed by 
tty_buf$slock and tty_buf$timerJock. 

If this dump is due to a manual return to BCE, then some pertinent lock information 
is also printed. 



Standard Subsystem Requests 



prints a line describmg the current invocation of azm. 

? 

prints a list of requests available in azm. 
abbrev, ab 

controls abbreviation processing of request lines. 
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answer 

provides preset answers to questions asked by another request 

do 

executes/returns a request line with argument substitution. 
exec_com, ec 

executes a file of azm requests that can return a value. 

execute, e 

executes a Multics command line. 

execute.string. exs 

substitutes arguments into a control string. 

help 

prints information about azm requests and other topics. 

if 

conditionally executes/returns one of two request lines. 
list_help, Ih 

displays the name of all azm info segs on given topics. 

list_requests, Ir 

prints a brief description of selected azm requests. 

quit, q 

exits azm. 

ready, rdy 

prints a Multics ready message. 

ready_off, rdf 

disables printing of a ready message after each request line. 
ready_on, rdn 

enables printing of a ready message after each request line. 

substitute_arguments, substitute.args, sbag 

substitutes arguments into a control string and prints the result on user_output 

subsystem^jiame 

prints/returns the name of this subsystem. 

sul^'stenuversion 

prints/returns the version number of this subsystem. 

The standard escape convention for executing Multics command lines (..) is also 
supported. 
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Name: as^who 

SYNTAX AS A COMMAND 

as_who {-control_args} {User_ids} 

SYNTAX AS AN ACT/VE FUNCTION 

[as_who {-control_args} {User__ids}] 

FUNCTION 

lists the contents of the answering service's user tables answer_table, absentee_iiser_table, 
and daemon.user_table in the directory >scl. As an active function, it returns 
Person_id.Project_id for the processes selected for output, separated by spaces. 

ARGUMENTS 

User_ids 

can be the access control names 

Person_id.Project__id 

lists all users logged in with the specified Person_id and Project.id. 

Person_id 

lists all users logged in with the specified Person__id. 
.Project_id 

lists all users logged in with the specified Projected. 
You can use the star convention. 
CONTROL ARGUMENTS 
-absentee, -as 

prints the ratio of absentee users logged in to the number of absentee slots 
currently available and then lists the absentee users. 

-channel chn_id, -chn chn_id 

lists only interactive users whose tty ID matches chn_id, daemon users whose 
source name (e.g., prta, vine, etc) matches chn_id, or absentee users whose 
absentee name (e.g., absl) matches chn^id. The chn_id argument can be a 
stamame (to cause several users to be listed). 

-connected 

prints a list of connected (interactive) processes only, 
-cpu 

shows CPU usage (in seconds) for the listed processes. You need access to 
metering^te_ or phcs_. 
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-daemon, -dmn 

prints the number of currently active daemon processes and then lists them. 

-disconnected, -disc 

prints a list of disconnected processes only. 

-group {name}, -gp {name} 

prints a list of users that fall under the specified load control group (see "Notes" 
below). 

-idle 

shows how long (in seconds) the listed processes have been idle. You need access 
to metering^te_ or phcs_. 

-interactive, -ia 

prints a list of all users having current interactive processes. 

-long, -Ig 

prints the long form of output including log-in time and tty ID. If you give no 
-Ig, the command prints the User_id (Person_id.Project_id) and flag for each user 
(see "Notes" below). 

-name, -nm 

sorts the users by name. 

-no_header, -nhe 

suppresses colimin headings and load control heading from the printed output 

-pdir_volume {lv_name}, -pdv {lv_name} 

either includes in the output the name of the logical volume containing the user's 
process directory segments (if you supply no lv_name) or prints information about 
only those users whose process directory s^ments are on the volume specified by 
lv_name. 

-process_id. -pid 

includes the process_ids for the listed processes. 

-project, -pj 

sorts the users by project 

-secondary, -sc 

prints a list of all users having currently active secondary user processes (see 
"Notes" below). 
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NOTES 

Access to the user table s^ments is usually restricted. If you lack access to these 
tables, use the who command (see the Commands manual, AG92) to list the whotab 
segment in >scl, which is a public list of logged-in users. 

The default sort is by login time. 

Anonymous users' true log-in names are shown, preceded by a *. 
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Specification of the -long control argument returns time of login, tty ID, weight, 
device channel, load control group, flags indicating special variables, and a User_id for 
each user. 

Included in the output next to the User_id are flags, indicating preemption attributes 
(primary or secondary status), and the current status of that user's process (these 
attributes vary according to the login instance and the discretion of the project 
administrator). When this command is invoked with the -long control argument, the 
column listing these flags has the heading "PNDS." The flags in these four column 
positions indicate the user's status with respect to: Preemption, Nolist, Disconnected, 
and Suspended status. Additionally, if the -idle control argument is specified, R and 
W flags can occur. An R flag indicates the process is ready: a W flag indicates the 
process is waiting for another event. 



Possible preemption attribute flags are: 
< blank > 

indicates that the user has primary status. 



X 
D 



indicates that the user has secondary status. 

the user has the nobump attribute (cannot be preempted). 



the user is subject to bumping (preemption) by other members of his project, 
whose grace period has not yet run out. 



the user has been bumped but has not yet logged out. 



identifies a daemon user. 
Possible nolist flags are: 
<"blank>" 

the user does not have the nolist attribute. 

N 

the user has the nolist attribute. 

Possible disconnected flags are: 

<blank> 

the user is not disconnected. 

D 

the user is disconnected. 
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Possible suspended flags are: 

<blank> 

the user is not suspended. 

S 

the user is suspended. 
EXAMPLES 

In the following example, the as_who command is invoked with the -long control 
argument, and the resulting output is printed: 

! as_who -long 

Multics mpp03221; Development Machine. 

Load =11.0 out of 70.0 units; users = 11 out of 70 

Absentee users = 1 background, 1 foreground; Max background absentee users = 3 
Daemon users = 7 

System up since Ok/ll/Zk I308.3 
Scheduled shutdown at 04/23/8^+ 23OO.O 



Last 


shutdown was 


at 


0l+/22/8i+ 


2307.7 






Log i n 


1 at 


TTY 


Load 


Chan 


Group 


PNDS 


User ID 


2119. 


1 


none 


1 .0 


a.hOl8 


SysProg 


> D 


Smi th.Mul t i cs 


2150. 


3 


001 


1 .0 


a.h019 


Adm i n 


> 


Jones .SysAdmi n 


2200. 


1 


Q 1 


1 .0 


abs 1 


Admi n 




Jones . SysAdm i n (crank) 


2207. 


k 


Q FG 


1 .0 


abs2 


SysProg 




Doe.Multics (load_tape) 


1308. 


k 


cord 


1 .0 


cord 


ID 


D 


1 0 . SysDaemon 


1308. 


6 


bk 


1 .0 


bk 


System 


D 


Backup .SysDaemon 


1308. 


G 


pr ta 


1 .0 


pr ta 


iO 


D 


1 0 .SysDaemon 


1308. 


6 


puna 


1 .0 


puna 


ID 


D 


1 0 .SysDaemon 


1308. 


7 


V i nc 


1 .0 


V i nc 


System 


D 


Vol ume_Dumper .SysDaemon 


1308. 


7 


nw 


1 .0 


nw 


System 


D 


Networ k_Daemon . Daemon 


1308. 


7 


ns 


1 .0 


ns 




D 


Network__Server . Daemon 



The following example invokes the as_who command to list all users on projects that 
begin with "Mi". 

! as who .Mi" 



The following example invokes the as_who command to list all users on the CompBar 
project whose names begin with "A". 

! as_who A -.CompBar 



2-48 



GB64-00 



backup_dump 



backup_dump 



Name: backup dump 

SYNTAX AS A COMMAND 
backup_dump path -control_args 

FUNCT/ON 

either dumps a single segment, directory, or subtree or uses a dump control file to 
dump a set of segments, directories and subtrees. It is one of the commands used to 
control hierarchy dumping of storage system segments and directories to magnetic tape. 
The other commands are: 

catchup_dump 
comp 1 ete_dump 
end_dump 
star t__dump 
wakeup_dump 

The backup_dump command is the most general of all the hierarchy dumping 
commands. It is called by the start_dump, catchup_dump and complete_dump 
commands to perform the actual dumping, after they have set certain perprocess static 
switches. In addition, you cmi use various control arguments to make the backup_dump 
command imitate the kind of dumping done by the start_dump, catchup_dump and 
complete_dump commands. 

The backup_dump command allows cross dumping, a feature not allowed by the other 
hierarchv dumping commands. That is. it allows a specified segment, directorv or 
subtree to be dumped to tape and recorded on the tape as coming from a different 
location in the hierarchy. 

You should note that argument processing for all of the hierarchy backup commands 
is performed by a common argument processing procedure. The values of all 
arguments are remembered in static storage and remain in effect for the life of the 
process, unless changed by arguments given in subsequent invocations of backup 
commands, it should also be noted that the dumping commands and the reloading/ retrieving 
commands are all part of the same hierarchy backup system, and argument values set 
by the dumping commands remain in effect for the reloading/ retrieving commands and 
vice versa, unless overridden. However, dumping and reloading cannot be done in the 
same process; use the new_proc command between dumping and reloading. See "Notes 
on Default Arguments" below. 

ARGUMENTS 

path 

is the absolute pathname of the segment, directory or subtree to be dumped. 
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CONTROL ARGUMENTS 
-all 

causes all directory entries (in the specified subtree) to be dumped, regardless of 
their dates modified or dates dumped. This argument overrides a previously given 
-dtd control argument or DATE argument. This is the default. 

-brief_map. -bfmap 

creates a map file that lists the processed entries. 

-control path 

indicates that path is the pathname of a dump control file. The suffix "dump" is 
assumed. For example, "-control sys_dirs" specifies a control file named 
sys_dirs.dump. in the working directory. See "Notes on Format of a Dump 
Control File" below. 

-debug 

disables those phcs_ and hphcs_ calls that deactivate dumped segments and set 
quotas. This allows nonprivileged users to use backup_dump to save copies of 
their hierarchies on tape. 

-destination STR, -ds STR 

specifies a destination for printing maps and error files. The default is 
"incremental" for maps and "error file" for error files. 

-dtd 

tests and dumps each segment only if the segment or its branch has been 
modified since the last time it was dumped. 

-error_of 

writes error messages into a file rather than online. The name of the error file 
is printed when the first error is encountered. This is the default. 

-error_on 

writes error messages on the user's terminal. 

-header STR, -he STR 

specifies a heading for dprinting maps and error files. 

-hold 

leaves the current hierarchy dump tape or tapes mounted and inhibits rewinding 
after the current hierarchy dump cycle is completed. 

-map 

writes a list of the segments and directories processed into a file. This is the 
default. 

-nodebug 

enables hphcs_ calls to set quotas and the transparency switches. This is the 
default. 
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-nohold 

rewinds and unloads the hierarchy dump tape or tapes at the end of the current 
dump pass. This is the default. 

-nomap 

inhibits listing of the names of processed segments and directories and turns the 
tape switch on (see -tape below). 

-nooutput 

inhibits writing hierarchy dump information even if the tape switch is on. This is 
used for a test run or debugging. 

-noprimary, -npri 

uses each pathname as given. The default is -primary. 

-notape 

inhibits writing of a hierarchy tape. This argument also causes a map to be 
created even if it was previously inhibited. (See -map above.) 

-only 

indicates that only the requested segment or directory and its branch are to be 
dumped. This is the opposite of -sweep. 

-operator STR 

indicates that STR is the user's name or initials (up to 16 characters in length), 
-output 

writes hierarchy dump information onto the tape if the tape switch is on. This is 
the default. 

-primary, -pr 

replaces all directory names in each pathname with the primary names. This is 
the default. 

-pvname STR 

indicates that segments and directories may only be dumped if they reside on the 
physical volume specified by STR. 

-request_type STR, -rqt STR 

specifies an output request type for printing maps and error files. Available 
request types can be listed by using the print_request_ types command (described in 
the Multics Commands and Active Functions manual. Order No. AG92). The 
default is "printer." 

-sweep 

indicates that the whole subtree beginning with the given directory is to be 
dumped, subject to the criteria of the -dtd control argument or the DATE 
argument if either has been invoked. This is the default. 
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-tape 

allows writing of a tape. This is tiie default, 
-tapes N 

indicates that N is the number of output tape copies to be made where N can be 
either 1 or 2. The default is 1. 

-Itape 

sets the number of tape copies to 1 as an alternative to the -tapes argument. 
-2tapes 

sets the number of tape copies to 2 as an alternative to the -tapes argument. 
DATE 

an argument beginning with a character other than "-" or ">" is assumed to be a 
date, in a formal acceptable to the convert_date_to_binary_ subroutine. If the 
argument can be converted to a date, then only segments and directories modified 
after that date are dumped. 

NOTES ON DEFAULT ARGUMENTS 

The values of arguments given to any of the hierarchy backup commands are 
remembered in static storage and remain in effect for the life of the process, unless 
explicitly changed during the invocation of a subsequent backup command. 

The following defaults are in effect for the dumper before any backup commands are 
given: they are not. however, reset to these values at the start of each backup 
command, except as noted. 

-a1 1 
-cont i n 
-error_of 
-map 

-nodebug 
-nohol d 
-output 
-pr imary 
-sweep 
-tape 
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The following defaults are set automatically at the time the respective commands are 
executed: 

catchup_dump 
-tape 

(default date yesterday at midnight) 

compl ete_dump 
-al 1 
-tape 

star t_dump 
-dtd 
-hold 
-tape 

-wakeup 60 



NOTES ON FORMAT OF A DUMP CONTROL FILE 

The control file specified by "-control path" is an ASCII segment containing absolute 
pathnames of entries (segments, MSFs. and directory subtrees) to be dumped, each on 
a separate line. Cross-dumping is specified by "=new_path" following a pathname, with 
no intervening spaces, where new_path is the pathname of the new parent directory if 
the string contains >'s: otherwise, it is a new entryname to replace the entryname 
portion of the pathname dumped. The entry is placed on the tape as if its pathname 
were the resulting new pathname. 



Name: backup load 

SYNTAX AS A COMMAND 
backup_load {path} {-control_args} 
FUNCTION 

either reloads the entire contents of one or more hierarchy dump tapes into the 
hierarchy, leaving it looking exactly as it did when "the dump tape was made, or uses 
a retrieval control file to reload a set of segments, directories and subtrees. It is one 
of the commands used for hierarchy reloading and retrieving of storage system 
segments and directories. The other commands are: 

reload (initializer command) 
reload (Multics command) 
re 1 oad_system_rel ease 
retr i eve 
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I The backup_ioad command is the most general of all the hierarchy reloading/ retrieving 

I commands. It is called by the reload and retrieve Multics commands, and by the 

I reload and reload_system_release initializer commands. It places its maps in the 

I v^orking directory and doesn't automatically dprint them. 

You should note that argument processing for all of the hierarchy backup commands 
is performed by a common argument processing procedure. The values of all 
arguments are remembered in static storage and remain in effect for the life of the 
process, unless changed by arguments given in subsequent invocations of backup 
commands. It should also be noted that the dumping commands and the reloading/retrieving 
commands are all part of the same hierarchy backup system, and argument values set 
by the dumping commands remain in effect for the reloading/retrieving commands and 
vice versa, unless overridden. However, dumping and reloading cannot be done in the 
same process; use the new_proc command betv^^een dumping and reloading. See "Notes 
on Default Arguments" belov^\ 

ARGUMENTS 

path 

is the absolute pathname of a retrieval control file (see "Notes on Format of a 
Retrieval Control File" below). This argument is optional. It can be given 
anywhere on the command line. 

CONTROL ARGUMENTS 

-all 

causes segments to be retrieved from the tape regardless of their date/ time 
dumped. This control argument overrides a previously given DATE argument. This 
is the default. 

-brief_map. -bfmap 
[ creates a map file that lists the processed entries. 

-debug 

disables those hphcs_ calls that set quotas and transparency switches. 

-destination STR. -ds STR 

specifies a destination for printing maps and error file. The default is 
* "incremental" for maps and "error file" for error files. 

-error_of 

writes error messages into a file rather than printing them. The name of the 
error file is printed when the first error is encountered. This is the default. 

-error_on 

writes error messages on the user's terminal, 
-first 

prevents searching a tape for additional copies of a requested segment or subtree 
after the first copy has been retrieved. 
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-header STR. -he STR 

specifies a heading for printing maps and error files. 

-last 

indicates that the last copy of a given segment or subtree on a tape or set of 
tapes is to be retrieved. This is the default. 

-map 

writes a list of the segments and directories processed into a file. This is the 
default. 

-nodebug 

enables hphcs_ calls to set quotas and the transparency switches. This is the 
default. 

-nomap 

inhibits listing of the names of processed segments and directories. 

-noprimary. -npri 

uses each pathname as given. The default is -primary. 

-noqcheck 

causes the hierarchy reload to be done with quota checking suspended. Access to 
hphcs_ is required. This is the default. 

-noquota 

inhibits resetting of quotas. See -quota. This is the default, 
-noreload 

inhibits actual hierarchy reloading of segments into the hierarchy. This control 
argument can be used with -map to create a table of contents of the tape. The 
-noreload control argument also causes the names that would have been reloaded 
to be put into the map. 

-nosetlvid 

inhibits the setting of the logical volume identifiers for each directory to be 
reloaded. 

-notrim 

inhibits deletion of entries in a directory. Entries can only be added or modified, 
-operator STR 

indicates that STR is the user's name or initials (up to 16 characters in length). 

-primary, -pri 

replaces all directory names in each pathname with the primary names. This is 
the default. 



2-55 



GB64-00 



backup_load 



backup_load 



-pvname STR 

indicates that segments and directories may only be reloaded onto the physical 
volume specified by STR. 

-qcheck 

causes quota restrictions to be enforced during the reload, 
-quota 

causes the quotas on directories being reloaded to be set to the values they had 
when the directories were dumped. Access to hphcs_ is required. 

-reload 

enables actual reloading of segments into the hierarchy. This is the default. 

-request_type STR, -rqt STR 

specifies an output request type for printing maps and error files. Available 

request types can be listed by using the print_request_types command (described in 
the Multics Commands and Active Functions manual, Order No. AG92 ). The 
default is "printer". 

-setlvid 

enables setting of the logical volume identifier for reloaded entries inferior to 
each directory reloaded. This is the default. 

-trim 

enables deletion of all entries in a directory not found in the copy of that 
directory being reloaded. This causes entries deleted from an earlier version of 
the directory to be deleted when a later version is reloaded. It has effect only in 
the case of a directory that is both on the tape and in the hierarchy. This is the 
default. 

DATE 

an argument beginning with a character other than or ">" is assumed to be a 
date in a format acceptable to the convert_date_to_binary_ subroutine. If it can 
be converted successfully, then the hierarchy retriever only retrieves segments and 
directories dumped at or after the given date /time. 

NOTES ON DEFAULT ARGUMENTS 

The values of arguments given to any of the hierarchy backup commands are 
remembered in static storage and remain in effect for the life of the process, unless 
explicitly changed during the invocation of a subsequent backup command. 
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The following defaults are in effect for the reloader and retriever before any backup 
commands are given: they are not. however, reset to these values at the start of each 
backup command, except as noted below. 

-all 

-error_of 
-map 

-nodebug 

-nohol d 

-noquota 

-pr imary 

-reload 

-setlvid 

-trim 

The following defaults are set automatically at the time the respective commands are 
executed: 

reload (initializer command), reload (Multics command), 
rel oad_system_rel fease: 
-quota 
-trim 

retr i eve: 
-al 1 

-noquota 
-notr i m 

All of the above commands: 
-map 



NOTES ON FORMAT OF A RETRIEVAL CONTROL FILE 

The hierarchy retrieval is controlled by an ASCII segment containing one line for each 
object to be retrieved. A line can contain a single pathnam.e or two pathnames 
separated by an equal sign. The left-hand side specifies the segment or directory 
sought and the right-hand side, if present, specifies the new name under which that 
entity is to be retrieved. The sought pathname must begin with a > and end with 
either an entryname or the characters >**. If an entryname is specified, a single 
object of that name is retrieved. 

if >** is specified, the entire directory hierarchy, beginning at the point indicated in 
the pathname, is retrieved. In this case, the right_hand pathname, if present, ends in 
the name of the directory under which these entries are to be reloaded. For example: 

>udd>one_di r>""=>udd>two__d i r 

If a new name is specified on the right, it can be either a pathname or an 
entryname. If an entryname is given, the single object found is loaded with its former 
pathname and the new entryname. 
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If two pathnames are specified, both are checked against the current hierarchy and a 
new pathname consisting only of the primary entryname is created. This new 
pathname, as well as the original, is then used in searching the hierarchy. For 
example, >udd>sd is translated into >user_dir_dir>SysDaemon and both versions are 
sought. Primary names are used unless the -noprimary control argument is in effect. 

A hierarchy retrieval control file can contain a maximum of 256 lines. 

EXAMPLES 

A hierarchy retrieval control file containing the line: 
>udd>Mul t i cs>5'fs'c 

searches the tape for directories and segments whose first two pathname components 
are >user_dir_dir>Multics. These items are retrieved as found. 

A hierarchy retrieval control file containing the line: 

>ldd>a>b>c 

searches the tape for the segment >library_dir_dir>a>b>c. This item is retrieved as 
found. 

A hierarchy retrieval control file containing the line: 
>ldd>a>b=c 

searches the tape for the segment >library_dir_dir>a>b. This item is retrieved under 
the name >ldd>a>c. 

A hierarchy retrieval control file containing the line: 
> 1 dd>x>y>»'s5'<=> 1 dd>2>y 

searches the tape for directories and segments whose first three pathname components 
are >library_dir_dir>x>y. These items are retrieved in the subtree >ldd>z>y. 
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Name: bind fnp 

SYNTAX AS A COMMAND 

bind_fnp pathname {-control__args} 

FUNCTION 

produces a core image segment that can be loaded into the FNP. It uses two control 
segments: a bindfile, which specifies the configuration that the FNP will support, the 
names and ordering of the object segments included in the core image, and the size 
of certain software tables; and an optional search rules segment, which specifies which 
directories are searched to find the object segments. 

ARGUMENTS 

pathname 

specifies the pathname of the bindfile. If pathname does not have a suffix of 
bind_fnp, one is assumed. 

CONTROL ARGUMENTS 

-cross_ref, -cref 

adds a symbol cross reference to the listing segment. If -cross_ref is specified, 
the listing is generated regardless of whether -list is also specified. 

-list. -Is 

produces a listing segment whose name is derived from the name of the bindfile, 
with the suffix changed to list. The listing segment is a record of the binding. It 
contains a copy of the bindfile, a load map, and any error messages generated 
during binding. 

-search, -se 

indicates that the user wishes to specify the rules used to search for Multics 
Communications System object segments being bound into the core image. If 
given, there must be a segment in the working directory containing an A.SCII list 
of relative pathnames of directories to be searched in the order in which the 
search is desired. By default, the working directory is searched. This segment 
must have the same entryname as the bindfile, but with the suffix changed to 
search. 

-version STR 

assigns a version of STR to the core image. The maxihium length of STR is four 
characters. If this control argument is given, it overrides the version keyword 
specified in the bindfile. 

NOTES 

A default bindfile is supplied with the system. In general, the only fields that a site 
administrator would change are: hsla, Isla, version, order, and the size keyword for 
the trace module. 
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When creating a new FNP core image, object segments that are unchanged must be 
extracted from the object archive (see the Multics Commands and Active Functions 
manual. Order No. AG92) into a directory in the search list before executing the 
bind_fnp command. 

The syntax of the bindfile is described in the Multics Communications Administrator's 
manual Order No. CC75. 



Name: before journal meters, bjmt 

SYNTAX AS A COMMAND 
bjmt {paths} {-contro]_args} 

FUNCTION 

displays metering information about data management before journal activity. The 
information provided summarizes activity on a per-system and per-journal basis. The 
reset capability sets the meters to zero for the process only. 

ARGUMENTS 

paths 

are pathnames of before journals for which metering information is to be 
displayed. If the .bj suffix is not present, it is added. If no pathname is 
specified, metering information is displayed for all journals currently active m the 
system. 

CONTROL ARGUMENTS 

-brief, -bf 

selects the brief format for reporting on before journal usage. This is the default, 
-long, -Ig 

selects the long format for reporting on before journal usage. This format 
includes a breakdown of each before journal manager operation performed during 
the current invocation of DMS. 

-report_reset, -rr 

reports on the meters and then resets them. 

-reset, -rs 

resets the meters to zero without printing a report. 
ACCESS REQUIRED 

Some portions of the long report require re access to dm_admin_gate_. Nonprivileged 
users can display the unrestricted portions of the report. 
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EXAMPLES 

Two sample invocations of this command appear below. The first displays the brief 
format (default), the second, the long format. 

bjmt 

Total metering time: 3:09:51 



Journals in use 1 of 64 

Pages held 0 of 700 (700 per journal) . 

Segments active in 

i4K pool 0 of kOO 

16K pool 0 of 150 

64K pool 0 of 60 

256K pool 0 of 25 



>s i te>dm>system_l ow>system__def au 1 1 . bj 

journal size 4000 

before images written 0 

before image bytes written 0 

times journal filled 0 

successful recycles 0 

control intervals recycled 0 

transactions started 1 

non null transactions 0 

avg before image/transaction 0 

avg bytes/before image 0 

avg bytes/transaction 0 

avg control intervals/recycle 0 

time stamp 11/12/84 I845.7 est Mon 

pages currently held 0 



bjmt -Ig 

Total metering time: 3^09:19 



Journals in use 1 of 64 

Pages held 0 of 700 (700 per journal) . 

Segments active in 

4K pool 0 of 400 

16K pool 0 of 150 

64K pool 0 of 60 

256K pool 0 of 25 
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Calls to 

begin transaction 1 
write before image 0 
wr i te abort mark 0 
wr 1 te commi t mark 1 
write fm post commit 0 
write fm rollback handler 0 
write rollback mark 0 
rol 1 back 0 

Synch wr i te 
attempts 0 
holds 0 

invalid - null DM stamp 0 
invalid - bad DM stamp 0 
invalid - bad BJ index 0 
invalid - bad time stamp 0 
tosses 0 

Other ring zero calls 
unl i nk 0 

activate 0 (0 denied) 
deactivate 0 
set stamp 0 
a 1 1 ocate 3 
free 2 



>s i te>dm>system_l ow>system_def au 1 1 . bj 

journal size 4000 
before images written Q 
before image bytes written 0 
times journal filled 0 
successful recycles 0 
control intervals recycled 0 
transactions started 1 
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non null transactions 0 

avg before image/transaction 0 

avg bytes/before image 0 

avg bytes/transaction 0 

avg control intervals/recycle 0 

time stamp ll/12/8it l8i*5.7 est Mon 

pages currently held 0 



Name: bootload_fs 

SYNTAX AS A COMMAND 
bootload_fs operation {args} 
FUNCTION 

allows you to operate on a copy of the bootload command environment (BCE) file 
system. This includes the ability to extract the real BCE file system and to replace it 
with this working copy. 

ARGUMENTS 

operation 

is an operation listed below under "List of Operations." 

args 

are arguments required by the designated operation. 
LIST OF OPERATIONS 

The operations are grouped into two categories. The first group determines the 
location of your copy of the BCE file system; operations in this group can also 
extract the real BCE file system and overwrite it with your copy. The second group 
operates on objects in your working copy of the BCE file system. 

OPERATIONS ON PARTITIONS 

discard_partition, dpart" 

Syntax* bootload fs discard partition {"control arg} 

discards the contents of the working copy of the BCE file system. Follow this 
operation by a read_partition, use^partition or init_partition operation. 
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The control arguments is 
-force, -fc 

discards the contents of the working copy of the BCE file system without 
querying you first 

init__partition, ipart 
I Syntax: bootload_fs i ni t_part i t ion {-control_arg} 

clears out the contents of the working copy of the BCE file system. The result 
of init_partition is a file system containing no files; the result of discard__partition 
is no file system at all. 

The control arguments is 

-force, -fc 

clears out the contents of the working copy of the BCE file system without 
querying you first 

I read__partition, rpart 

Syntax: boot1oad_fs read_parti t ion pv_naine part_name 

reads the BCE file system from a specified disk partition into your working copy 
of the file system, overwriting the previous contents of your copy. You n^ 
access to hphcs_. 

The arguments are 

pv_name 

is the name of a mounted physical volume. 
part_name 

is the name of a partition on the specified volume to be read. 



save_partition, svpart spart 

Syntax: bootload__fs save_partl t ion path 

saves the current contents of your working copy of the BCE file system into a 
segment 

The arguments is 
path 

is the pathname of a segment that is overwritten with your working copy of 
the BCE file system. 
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use__partition, upart 

Syntax: bootload^fs use_part i t ion path 

copies the contents of a user-specified segment to become your working copy of 
the BCB file system. 

The arguments is 

path 

is the pathname of a segment that overwrites the current contents of your 
working copy of the file systenL 

write_partition, wpart 

Syntax: bootload_fs wr i te_parti tion {pv__name {part_name}} 
{-control_args} 

replaces the BCE file system found in the specified disk partition with your 
working copy. You need access to hphcs_. 

The arguments are 

pv_name 

is the name of a mounted physical volume. 
part_name 

is the name of a partition on the specified volume to be read. 
The control arguments is 
-force, -fc 

overwrites the old partition without querying you first 

If you supply no arguments, write_partition uses the identity of the partition last 
specified in a read_partition operation. 

OPERATIONS ON FILES 

delete^files, delete, dl 

Syntax: bootload_fs delete__fMes flle^name 
deletes files from the working copy of the BCE file system. 
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The arguments is 
file_name 

is the name of a file that is to be deleted from the BCE file system. 
list_files, list. Is 

Syntax: bootload__fs list_files 

lists the names and lengths (in characters) of the files in the working copy of the 
BCE file system. 

read_file, read, r 

Syntax: bootload_fs read__file file__name path 

extracts a file from the working copy of the BCE file system and places it into a 
Multics storage system file. 

The arguments are 

file_name 

is the name of a file within the working copy of the BCE file system. 

path 

is the pathname of the Multics file into which the BCE file is to be copied. 

rename.file, rename, m 

Syntax: bootload_fs rename_file o 1 d_f i 1 e_name new^f i 1 e_name 
renames a file within the working copy of the BCE file system. 
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The arguments are: 
old_file_name 

is the name of an existing file in the BCE file system. 

new_file_name 

is the new name to be given to the old file. 



write_file, write, w 

Syntax: boot]oad__fs write^file path fi1e_name 

places a copy of a Multics storage system file in the working copy of the BCE 
file system. 

The arguments are: 

path 

is the name of a file in the Multics hierarchy to be copied into the BCE 
file system. 

file_name 

is the name the copy is to have within the BCE file system. 



Name: cache meters 

SYNTAX AS A COMMAND 
cache_nieters {-control_args} 
FUNCTION 

interprets and prints per -system metering information on central processor, hardware 
recoverable, cache memory errors. 

CONTROL ARGUMENTS 

-brief, -bf 

inhibits the display of lines that are all zero. The default is to display all 
counters even if they are all zero. 

-cpu {tagl...tagN} 

displays fault counts for those processors specified by tagi. Tag may be one of 
the letters a through h or A through H. If tag is omitted, all processors are 
selected. 
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-report_reset, -rr 

generates a full report and then performs a reset operation. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 
the last call with -reset specified. If -reset has never been given in a process, it 
is equivalent to having been specified at sj'stem initialization time. The metering 
interval is reset for ALL processors. 

-total -tt 

displays total error counts for all processors. This is the default. 
NOTES 

If all of a processor's cache counters are zero, that processor is omitted from the 
display. 

The following is a brief description of the variables printed by the cache_meters 
command. 

CPU Tag 

is the tag or name of the processor. 
Cache Type 

is the type of processor cache and cache size. 

Primary Dir Parity /MultiMatch 

the processor detected a parity or multiple match in the primary cache directory. 
This condition causes the processor to abort the cache cycle and go to backing 
store for the data. Ths counter is valid for all processors and cache types. 

The following counters are valid only for DPS 8 processors: 

PT X Buffer OVFL/PAR/SEQ Err 

either the processor's Write-Notify buffer logic could not keep up with 
Wriie-Notify signals for the port specified by X (A. B. C or D), or the processor 
detected a parity or sequence error on the specified port. Detection of this 
condition causes the processor to flush cache. 

Primary DIR/PT Buffer Overflow 

the processor's primary cache directory or port Write-Notify buffer logic could 
not keep up with Write-Notify signals. This condition forces the processor to 

flush cache. 

WNO Parity ANY Port 

the processor detected a parity error on the data or address protion of the 
Write-Notify signal for port A, B, C or D. This condition forces the processor 
to flush cache. 
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Level N Dup Dir Parity 

the processor detected a parity error in the duplicate cache directory match logic 
for the level specified by N (0, 1. 2 or 3). This condition forces the processor to 
flush cache. 

Dup Dir MultiMatch 

the processor detected a multiple match condition in the duplicate cache directory. 
This condition forces the processor to flush cache. 



Name: change kst attributes 

SYNTAX AS A COMMAND 

change_kst_attr i butes {-control_arg} target attribute 
FUNCTION 

allows a user to change selected per-process attributes of a segment. 

ARGUMENTS 
target 

specifies the segment whose known segment table (KST) attributes are to be 
changed. Either a relative pathname or an octal segment number can be supplied. 

CONTROL ARGUMENTS 

-name, -nm 

is only used if the target is a relative pathname that looks like a segment 
number. 

LIST OF ATTRIBUTES 

One or more of the following m.ust be given: 

allow_deactivate 

if set, permits explicit deactivation of the segment. 

allow_write 

if set, the user is not prevented from writing into the segment or directory if she 
or he has permission to do so. 

tms 

if set, date-time-modified is not updated on the account of the user. 
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tpd 

if sei, pages of this object are not placed on the paging device on the account of 
the user. 

tus 

if set, date- time-used is not updated on the account of the user. 
ACCESS REQUIRED 

This command requires access to the hphcs_ gate if the tms or tus attributes are to 
be set: otherwise, access to the phcs_ gate is required. 

NOTES 

Because directories are activated v.'hen their segment numbers are assigned, it is not 
possible to set meaningfully the tpd, tms. tus, or allow_deactivate attributes for a 
directory. 

If an attribute is preceded by the circumflex character (^), then the attribute is reset: 
otherwise, the attribute is set. Attributes not mentioned are unaffected. 



Name: change„tuning_parameters, ctp 
SYNTAX AS A COMMAND 

ctp name! valuel {... nameN valueN} {-contro l_arg} 
FUNCTION 

used to change the value of several tuning parameters within the system. 

ARGUMENTS 

namei 

is the name of a tuning parameter whose value is to be changed. It can be either 
the long name or the short name of the parameter. 

valuei 

is the representation of the value to which the tuning parameter is to be set. It 
typically can be an integer, a decimal number of seconds, either "on" or "off," a 
decimal number, or a full word octal value. The data type of the value depends 
on the individual tuning parameter being set. The data type of each valid tuning 
parameter is described in the Multics System Maintenance Procedures manual. 
Order No. AM81. 
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CONTROL ARGUMENTS 
-silent 

causes the message normally printed on the operator's console to announce the 
change not to be printed but only to be logged. You can use -silent only in the 
Initializer's process. 

ACCESS REQUIRED 

You need access to metering_gate_ and to hphcs_. If you give -silent, ctp requires 
access to initializer_gate_ also. 

NOTES 

Before making any change, you are shown the change and asked if it is correct The 
first pair of values represent the old and new values of the parameter, while the 
second pair of values (parenthesized) represent the octal contents of the word in the 
database where that parameter is kept You must respond "yes" followed by a newline 
character for the change to be made. Invalid parameters are rejected. The current 
values of the parameters can be obtained by using the print_tuning_parameters 
command. (For comprehensive descriptions of the tuning parameters and their effects, 
see the Multics System Maintenance Procedures Manual, Order No. AM81.) 



Name: change_„voIume_registration, cvr 

SYNTAX AS A COMMAND 
cvr -control_args 

FUNCTION 

changes the registration information for a physical or logical volume. 
CONTROL ARGUMENTS 

The -pv or the -Iv control argument is required and must immediately follow the 
conmiand name. 

The following control arguments change the registration of a physical volume. They 
are recognized only when the first control argument is -pv. 

-date_registered DT^STR, -date DT_STR 

specifies the date the physical volume was registered on. Normally this is 
generated by the software automatically. Use -date only in correcting registration 
data after a system failure. 
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specifies the Honeywell model number for the disk device. Use -model only in 
correcting registration information before volume initialization or after a system 
failure. Inconsistancies between medium label information and the registered 
information causes difficulties in volume mounting. The following values are valid 
for N: 



VALUE 


DEVICE 


koo 


MSUOitOO 


402 


MSU0402 


451 


MSU0it51 


500 


MSUO5OO 


501 


MSUO5OI 


3380 


MSU338O 


3381 


MSU3381 



-location STR, -loc STR 

specifies the current location of the disk pack. This is for administrative 
information only. STR can be any 32 characters (e.g., "offline — in cabinet 13"). 

-manuf acturer_serial STR, -serial STR 

specifies the serial number of the physical medium. This is for administrative 
information only. STR can be any 32 characters (e.g., "Memorex — M234634"). 

-name PV.NAME, -nm PV_NAME 

specifies that the name of the physical volume is to be changed. Use -nm only 
in correcting registration information before volume initialization or after a system 
failure. Inconsistancies between medium label information and the registered 
information causes difficulties in volume mounting. 

-physicaLvolume PV_NAME. -pv PV_NAME 

specifies the name of the physical volume for which the registration data is to be 
changed. (Required, if fdiysical volume registration changes are desired) 

-physical_volume_uid UID, -pvid UID 

specifies the new unique ID of the physical volume. A UID is a string of one to 
12 octal digits. Use -pvid only in correcting registration information before 
volume initialization or after a system failure. Inconsistancies between medium 
label information and the registered information causes difficulties in volume 
mounting. 
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The following control arguments pertain to changing the registration of a logical 
volume. Thev are recognized only when the first control argument is "-logical_volume" 
(or "-Iv"). 

-access_class MIN_AUTH {:MAX_AUTH} 

specifies the AIM authorization of users allowed to attach the volume. The 
authorization can be specified by a minimum authorization value and a maximum 
authorization value, in which case users at any authorization in the range are 
allowed to attach the volume. Alternatively, the authorization can be specified as 
a single value, in which case only users at the specified authorization are allowed 
to use the volume. The authorization values must be specified using valid 
site-defined authorization strings. Use the print_auth_names command for a list 
of valid authorization values. This control argument should only be used in 
correcting registration information before volume initialization or after a system 
failure. Inconsistancies between medium label information and the registered 
information will cause difficulties in volume mounting. 

-acs_path PATH, -acs PATH 

specifies the pathname of the access control segment (ACS) for the volume. The 
ACS itself is not created, but must be created at the specified path and the 
desired access control list set (see "Notes" below). The name of the entry must 
be {lv_name} .acs. If this control argument is not given when registering a public 
volume, only the volume owner will have executive privileges (everyone will have 
read /write privileges, given proper access to the hierarchy). If this control 
argument is not given when registering a non-public {i.e. a private) volume, the 
default ACS pathname will be: >udd> {owner's project_id} > {owner's 
person_id} > {'lv_name} .acs> 

-logical_volume LVNAME, -Iv LV_NAME 

specifies the name of the logical volume for which to change the registration 
data. This control argument is required and must immediately follow the 
command name (if logical volume registration changes are desired). 

-logical_volume_uid UID. -Ivid UID 

specifies the new unique ID of the logical volume. A UID is a string of 1 to 12 
octal digits. This control argument should only be used in correcting registration 
information before volume initialization or after a system failure. Inconsistancies 
between medium label information and the registered information will cause 
difficulties in volume mounting. 

-name LV_NAME. -nm LV_NAME 

specifies that the name of the logical volume is to be changed. This control 
argument should only be used in correcting registration information before volume 
initialization or after a system failure. Inconsistancies between medium label 
information and the registered information will cause difficulties in volume 
mounting. 
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-owner USER_ID, -ow USER_ID 

specifies the user who is to act as the primary volume administrator. This user 
has the privilege of granting executive access to other users via the ACS, granting 
read /write access to others via the ACS (for private volumes), and for setting up 
volume quota accounts. The person_id or project_id may be specified as 

-public STR 

specifies whether the new logial volume is to be private or public. The value of 
STR can be yes (public) or no (private). This control argument should only be 
used in correcting registration information before volume initialization or after a 
system failure. Inconsistancies between medium label information and the registered 
information will cause difficulties in volume mounting. 

EXAMPLES 

cvr -pv pub3^ -serial c886 -loc dskc_13 

This command will change the registered serial number and location of the physical 
volume "pub34". 

cvr -Iv ZenDisk -owner Jones . Zen_Res 
This command will change the registered owner of the logical volume "ZenDisk". 
NOTES 

Phvsical volume names are restricted to lowercase letters, digits, and the underscore 
("_""). 

If any of the following control arguments are given, the user is queried to determine 
if the changes are intentional. This is to avoid problems in volume mounting due to 
errors in the registration. They are: 

-logical _vo 1 ume_u i d 
-phys i ca l_vol ume_u i d 
-access_c 1 ass 
-devi ce__niode1 
-name 

Please note that these control arguments should be used only to correct the volume 
registration data before the volume in question is actually initialized or after system 
failure. The medium label information is not changed. Inconsistancies between the 
label and registration data will cause difficulties in mounting the volume. 

ACCESS REQUIRED 

The user of this command is required to have "re" access to the mdc_rpiv_ gate and 
"s" to -Iv. Also, if any name or UID is to be changed, "sm" is required to >lv. 
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Name: channel comm meters 

SYNTAX AS A COMMAND 

channel _comm_meters channel_name {-contro1_args} 
FUNCTION 



prints out metering information for a specified communications channel or channels. 

ARGUMENTS 

channel_name 

is the name of the channel for which information is to be printed- If it is the 
name of an FNP, totals for that FNP are reported. If channel_name is a 
starname, information for every channel matching the starname is printed. 

CONTROL ARGUMENTS 

-brief, -bf 

causes a reduced amount of information to be printed for each specified channel, 
-error 

causes only those meters to be printed that reflect error conditions. 

-since_bootload. -boot 

prints the meters accumulated since each channel's parent multiplexer {or, in the 
case of an FNP, the system) was last loaded. This control argument is 
incompatible with -since_dialup (below). 

-since_dialup, -dial 

prints the meters accumulated since the channel last dialed up. This is the 
default. This control argument is incompatible with -since_bootload (above). 

-summary, -sum 

causes a one-line summary to be printed for each specified channel. This control 
argument may not be specified if either -brief or -error is specified. 

ACCESS REQUIRED 

If a single channel is specified, the caller must either be the current user of the 
specified channel or have access to either the metering gate gate or the phcs_ gate. 
If a starname is specified, the user must have access to one of the above-named 
gates. 

NOTES 

If -brief and -error are both specified, then only those error indications that would 
be printed with -brief are printed. See the example below. 
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tXAMt^Lt::) 

In the example below, code characters appear at the beginning of some lines; these 
characters do not appear in the actual output of the command. The interpretation of 
the characters is as follows: 

A — this line appears for asynchronous channels only 

S -- this line appears for synchronous channels only 

B -- this line is among those printed if -brief is specified 

E -- this line is among those printed if -error is specified 

Only lines marked with both B and E are printed if -brief and -error are both 
specified. 

channel_comm_meters a.hOOO 
Total metering time 01:it5:13 
a.hOOO 

[The following meters are printed for all nonmul t i pi exed channels:] 



B Total characters input 

B Total characters output 

B Average length of input 

B Average length of output 



before conversion 
984 
ICSiiO 
8.7 
63.1 



after conversion ratio 

935 0.95 
11,400 1.09 

8.3 
69.4 



Number of calls 

Average time per call (msec.) 

Average chars, processed per call 



read 

175 
2.3 
5.6 



wr i te 
194 

5.8 
56. 1 



control 
53 
1.7 



total 
422 
4.1 



Number of software interrupts 113 
Average time per interrupt (msec.) 1.6 

B Effective speed (bps) 1.6 



17.5 



[The following meters are printed for physical FNP channels only] 







i nput 


output 


SB 


Messages transmitted 


240 


224 


SB 


Minimum message length 


5 


12 


SB 


Maximum message length 


1^3 


508 


SB 


Average message length 


10.3 


57.6 


SBE 


Invalid input messages 


6 {2.5% of total) 


SBE 


Output messages retransmitted 


Q 1 1 r 0, 
0 V < • O'b 


of total) 


SBE 


Timeout waiting for acknowledge 


2 (0.4% 


of output messages) 



Output overlaps in FNP 127 
Average length of DIA request queue I.7 entries 
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A Pre-exhaust status 12 

A E Exhaust status 7 

A E Software transfer timing errors 0 

A E Bell/quits 8 

A E Echo buffer overflows 2 

E Par i ty errors 0 

Avg. number of pending status events 1.9 

E Software status queue overflows 1 

E Hardware status queue overflows 0 

E Input buffer allocation failures 1 

[The following meters are printed for an entire FNP] 

FNP has been up for 0^:15:12 

B Number of channels configured 88 

B Average number dialed up ^3-7 

B FNP idle 7^.9% 

B Idle at peak load 8.0% 

input output 

B Characters transmitted 71,966,i+00 9^,934,400 

B Characters per second 4,700 6,200 

E Abnormal DIA status events 3 

E Memory EDAC errors 0 

B Memory size 64K 
B Total available buffer pool 6,3^0 words 
B Avg. amount of free space 21,876 words 

B Average % of buffer pool available 3^-7 

BE Buffer allocation failures 12 

E Output restricted by space 2k 



Number of interrupts from this FNP 1,964,208 

Avg. t ime/ i nter rupt (ms) 3'1 

% of total CPU time 1 . 1 

Mailbox transactions: 

Input data 220,349 

Output data 543,210 

I nput control 14,1 i i 

Output control 23,456 



Total 801,126 

Average inbound mailboxes in use 1.1 

Average outbound mailboxes in use 3-1 

Maximum outbound mailboxes in use l6 

E No outbound mailbox available 37 
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t Input rejects 22 
E % of input transactions rejected 0.01 

The following example shows the format of the output of the command when the 
-summary control argument is specified. 

channel_comm_meters a.hOO'v -summary 



cps 


cps i 


cpso 


i otxXsbepQqa 


err 


ABE 


name 


user 


120 


0.2 


5.^ 


xX b Q 


12 


aB 


a.hOOO 


Coren 


600 


2.1 


102.1 


t X a 


73 


s 


a.hOOS 


ABClone 


30 


0.5 


2.6 


e 


2 


a E 


a.h009 


Parr i sh 



The column headings are interpreted as follows: 
cps 

is the nominal speed of the channel, in characters per second. 

cpsi 

is the effective speed of input over the channel, in characters per second. 

cpso 

is the effective speed of output over the channel, in characters per second. 

The following flags are printed if the corresponding condition has occurred at least 
once on the channel. 



invalid input message 

0 

output message retransmitted- 

t 

timeout waiting for acknowledge 

X 

pre-exhaust status 

X 

exhaust status 



2-78 



GB64-00 



channel_comm_meters channel_comm_meters 



s 

software transfer timing error 

b 

bell /quit 

e 

echo buffer overflow 

P2 

parity error 

Q 

software status queue overflow 

q 

hardware status queue overflow 

a 

input buffer allocation failure 

err 

is the total number of errors of all kinds that have occurred on the channel. 

A 

is "a" for an asynchronous channel or "s" for a synchronous channel. 

n 

is the channel is in breakall mode. 

E 

is the channel is in echoplex mode, 
name 

is the name of the channel. 

user 

is the Personid of the current user of the channel. If the channel is not in use, 
or the user's name is not available, this field is left blank. 
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Name: charge disk 

SYNTAX AS A COMMAND 
charge_disk {path} {-contro l_arg} 
FUNCTION 

is used by the daily disk accounting job (diskreport in the master, ec segment) to 
record the disk usage figures for each project in the project's projfiie entry. The 
figures are obtained from the disk_stat file that is produced by the sweep command. 
Figures are recorded only for directories in the subtree below >udd. Within that 
subtree, charging may be enabled or disabled on a per-logical-volume basis. 

ARGUMENTS 

path 

is the pathname of the disk_stai file from which the disk usage figures are 
obtained. The default is the segment. disk_stat. in the workmg directory. 

CONTROL ARGUMENTS 

-logical_volume namel name2 ... nameN 

-Iv namel namc2 ... nameN 

where namei is one or more logical volumes for which charging is to be enabled. 
Charging for all other logical volumes is disabled. If this argument is not given, 
it is assumed that all directories under >udd have their segments on the same 
logical volume, and charging for this volume is enabled. The sons logical volume 
identifier of the first project directory encountered is used as the logical volume 
identifier of the volume for which charging is enabled. 

NOTES 

Dollar charges are not computed by charge_disk. It records the total month-to-date 
time-page product (tpp) for all directories inferior to each project directory in the 
project's projfiie entry. The corresponding dollar charge is computed by the print_disk 
command for printing only. The disk charge actually billed is computed during 
monthly billing, using the disk price in effect at that time. {Thus a change in the 
disk price made before billing is retroactive to the beginning of the billing period.) 
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If the total tpp for a project, as computed from the figures in disk_stat, is less than 
the previous day's month-to-date tpp recorded in projfile, an error message is printed, 
and the projfile figure is not changed. This situation can arise in several ways, 
through system or human error. If a project directory is destroyed and then 
re-created in a wsl}' that sets its tpp integrator back to zero instead of to the 
previous value, charges start accruing from the date of the re-creation and the charges 
for the portion of the month preceding the destruction are lost. When this happens, 
the set_tpp command can be used to add the charge in projfile to the tpp integrator 
of the project directory. Before this is done, however, the system administrator should 
analyze the situation carefully, to be sure that adding this charge to the project is the 
correct thing to do. If it is determined that the projfile figure is the one in error, 
the edit_projfiie command can be used to correct it. 



Name: check cpu speed 

SYNTAX AS A COMMAND 
check_cpu_speed {cpu_tags} 

FUNCT/ON 

performs a relative check of the speed of a currently running CPU on the system. 

ARGUMENTS 

cpu_tags 

are the tags of CPUs configured on the system. If more than one is supplied, the 
values must be separated by spaces. The default is to run on all CPUs listed b}' 
the list_proc_required command that are currently marked as ON in the 
configuration deck. 

ACCESS REQUIRED 

This command requires access to the phcs_ gate to run. 
NOTES 

Your process is left running with the original set of system CPUs. 

The command runs on a CPU outside of your original set of CPUs if the CPU tag is 
given on the command line. 
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Name: check dir 

SYNTAX AS A COMMAND 
check_dir d i r_name {User_ids} 

FUNCTION 

scans a directory and reports the names of all segments whose bit count author is not 

equal to any one of the specified User_ids. 

ARGUMENTS 

dir_name 

is the directory to be scanned. 

User_ids 

are access names of the form Person_id.Project_id.tag. Any component may be 

"*" and omitted components are assumed to be "*". If no User_ids are specified, 
the User_id of the caller is assumed. 

NOTES 

For each segment whose bit count author does not match any of the specified 
User_ids. a line is printed giving: 

entryname date/time modified author 



Name: check mdcs 

SYNTAX AS A COMMAND 
check_mdcs volume 
fUNCT/ON 

checks for valid format and invalid unique identifier (UID) pathnames in the master 
directory control segment (MDCS) for a given volume. These segments are found in 
>lv, and are sometimes damaged by system crashes. Any errors found are reported via 
the syserr log and, if possible, corrected. 
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ARGUMENTS 
volume 

is the name of a storage system volume. 
ACCESS REQUIRED 

Access to the mdc_priv_ gate is required. 



Name: check mst 

SYNTAX AS A COMMAND 

check_mst REEL_NAME {-control_args} 

check_mst -file MST_F I LE_NAME {-control_args} 

check_mst -tape REEL_NAME {-control_args} 

check_mst OUTPUT_F I LE_NAME 

FUNCTION 

scans a Multics system tape (MST). producing a report on the segments it defines and 
checking for certain errors and inconsistencies. 

ARGUMENTS 

REEL_NAME 

is the name of the reel to be checked containing an MST written with 
generate_mst. 

MST_FILE_NAME 

is the pathname of the file created by generate_mst -file. 

OUTPUT_FILE_NAME 

is the name to be given to the output file if the input file has already been 
attached by generate_mst -hold. 

CONTROL ARGUMENTS 

-density N, -den N 

specifies the recorded density of the MST. 

-severity N, -sv N 

specifies the minimum severity of errors to be printed. 
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NOTES 

After the segments have been listed a cross-reference is run over the contents of the 
tape, to detect links to nonexistent segments or entry points or types of links that the 
hardcore prelinker cannot snap. The cross-referencer produces messages for links 
between temporary segments (temp segs) and other segments thai do not exist: for 
example, a collection 1 temp seg cannot legally reference a collection 2 segment 
because the first is guaranteed to have been deleted before the second is loaded from 
the tape. 

Next, the cross-referencer produces four sorted lists: 

1. A list of references to entrypoints that cannot be found in segments. These are 
usually errors. 

2. A list of links to segments that cannot be found on the MST, but are present in 
your search rules. This is a normal occurrence, since many hardcore programs 
check their ring of execution and make appropriate calls. When producing a 
modified system tape, check this list. 

3. A list of segments that cannot be found at all. Unless the code that uses them is 
not executed, or unless they are installed online, they produce linkage errors. 

4. A list of links to special star segnames (*system, *symbol. etc.): *system links 
cannot be used in the hardcore, and the symbol section of hardcore program.s is 
not retained: thus investigate any entries in this list. 

NOTES ON OUTPUT FORMAT 

This command produces an output file named REEL_NAME.ckrout (or 

OUTPUT_FILE_NAME.ckrout) that contains a list of the segments on the tape, as 
v^'ell as diagnostic information. For each segment there is an entry of the form: 

PRIMARY_NAME SEGNO (W, R, E) ATTRIBUTES] 
NAME2 ATTRiBUTES2 
NAME3 ATTRIBUTES3 
NAME4 PATHNAME 
NAMES 

ACL LIST 
where: 

FRIMARY.NAME 

is the primary name of the segment. 

NAME1...NAMEN 

are additional names of the segment. Names that are not printed to the left of 
ATTRIBUTES are printed in a third column. 
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W, R, E 

are the segmeni ring brackets, in the conventional order. 
ATTRIBUTESl 

are the standard SDW access attributes for the segment: read, execute, write, 
privileged, encacheable, gate, and wired. The gate attribute is derived from the 
ring brackets. 

ATTRIBUTES2 

are chosen from 

init seg 

a segment that is deleted at the end of system initialization, 
temp seg 

an init seg that is deleted when its collection is complete, 
per process 

segments in the Initializer's process directory, 
firmware 

segments that contain MPC firmware images. 
ATTRIBUTES3 

indicate that the segment has one of the following types of storage allocated or 
that no storage is allocated: 

wired length 

is the amount of memory used rounded up to an even 16-word boundary. 
This attribute is only meaningful for segments loaded before paging has been 
initialized. 

paged length 

is the length in pages of a segment that is either loaded after paging is 
initialized or that is made paged. The latter results in entries for both wired 
length and paged length. 

max length 

is a standard file system max length, and is set for segments that grow 
dynamically. 

PATHNAME 

is the pathname the segment gets, if any. 

ACL LIST 

is a standard access control list. 
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NOTES ON ERROR MESSAGES 



The checker detects and reports on several classes of errors: 



SEVERITY 4~FATAL 

the tape is malformed and cannot be read. This can be due to a logic error in 
generate_msi or tape I/O errors. 

SEVERITY 3~SEVERE ERROR 

a segment has run out of space or the rules for the system tape have been 
violated. The checker keeps track of the amount of space used in the linkage 
segments, definitions., and name_table. If an error indicates a wired overflow, 
then increase the cur_length specified in the header file to the size given in the 
total summar}' in the output file; if the error indicates a paged overflow, increase 
max_length. 

SEVERITY 2~ERR0R 

the cross-referencer finds references to entrypoints that were undefined in their 
containing segments or segments that cannot be found. 

WARNING 

other errors detected by the cross-referencer. 

Checker errors are reported by com,_err_ and are written to the output file. 

There is a severity indicator that is zero, or one if there were no errors detected. It 
is accessible with the severity active function: 

! [severity check_mst] 



Name: check sst size 

SYNTAX AS A COMMAND 
check_sst_s i ze {-control_args} 
FUNCT/ON 

displays the sizes of the system segment table (SST) header, active segment table (AST) 
hash table, and each of the 4 pools that are found in ssi_seg along with the total size 
of the sst_seg. 

CONTROL ARGUMENTS 

-4k N 

specifies that the 4k AST pool is to have N entries. 
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-16k N 

specifies that the 16k AST pool is to have N entries. 
-64k N 

specifies that the 64k AST pool is to have N entries. 
-256k N 

specifies that the 256K AST pool is to have N entries. 

-pathname STR, -pn STR 

specifies that the configuration deck with a pathname of STR is to be used. 

NOTES 

If you use no -4k, -16k, -64k, or -256k, a configuration deck sst card is used to 
supply the missing value(s). 

The configuration deck, if needed, is found with your search rules if you don't use 
-pn on the command line. 



Name: €bec4£_tc_data_size 
SYNTAX AS A COMMAND 
check_tc_data__s i ze {-control _args} 
FUNCTION 

displays the sizes of the active process table (APT) and inter-process transmission table 
(ITT) that are allocated in the tc_data segment | 

CONTROL ARGUMENTS 

-apt N 

specifies that the AFT is to have N entries. | 
-itt N 

specifies that the ITT is to have N entries. | 

-j^thname STR, -pn STR. 

specifies that the configuration deck with a pathname of STR is to be used. 
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NOTES 

The sizes of the APT and ITT databases are controlled by the values found on the 
ted configuration card. You can use this command to determine if a proposed change 
to the ted values will cause the tc_data segment to become larger than 255 pages. You 
can also use it to fill in the last page of the tc_data segment through manipulation of 
either of the values on the ted card. 

If you use neither -apt nor -itt, a configuration deck is used to supply the missing 
value(s). 

The configuration deck, if needed, is found with your search rules if you don't use 
-pn on the command line. 



Name: clean^card__pool 

SYNTAX AS A COMMAND 

cl ean_card_pool -age n {-control _arg} 

FUNCTION 

deletes inactive card image segments, in the >daemon_dir_dir>cards subtree, created by 
the system card reading process. 

ARGUMENTS 

-age N 

deletes all segments in person directories in the pool and all person directories 
whose date-time-modified (dtm) is older than N. 

CONTROL ARGUMENTS 

-quota N 

indicates that N pages of unused quota are to be left on each remaining access 
class directory. If N is 0, the quota is set to the "Number of pages used." 
(Default* 0) 

ACCESS REQUIRED 

You must be able to call the system_privilege_ gate. 
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NOTES 

After the pool is cleaned, all empty person directories and access class directories are 
deleted. All links and directories contained in a person directory are deleted regardless 
of age. All links and segments in an access class directory are deleted regardless of 
age. 



Name: clear partition 

SYNTAX AS A COMMAND 

cl ear_part i t i on pvname partname {control_args} 
FUNCTION 

overwrites the contents of a disk partition with zeroes or optional user-supplied 
pattern words. 

ARGUMENTS 

pvname 

is the name of the physical volume on which the partition to be cleared exists, 
partname 

is the name of the partition to be cleared. It must be four characters or less 
long. 

CONTROL ARGUMENTS 

-brief, -bf 

produces brief format messages. 

-long, -Ig 

produces longer format messages. (Default) 
-pattern word 

overwrites the partition with data consisting of the specified octal pattern word. 
The specified word is written into every location in the partition. If you give no 
-pattern, a default of all zeroes is used. 

ACCESS REQUIRED 

You need access to the phcs_ and hphcs_ gates. 
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fyu/ CO 

You are always queried whether the partition should be overwritten; by default the 
contents of the first eight words in the partition are displayed (in octal and as ASCII 
characters) as part of this question, to aid in preventing accidental overwriting of the 
wrong partition. 

See also dump_partition and list_partitions. 



Name: clear projfile 

SYNTAX AS A COMMAND 
cl ear_proj f i 1 e {path} 
FUNCT/ON 

is used after monthly billing to remove the entries for deleted projects from the 
project file. 

ARGUMENTS 

path 

is the pathname of the project file. The default is the segment, projfile. in the 
working directory. 



Name: clear reqfile 

SYNTAX AS A COMMAND 
clear_reqfile {path} 
fUNCT/ON 

is used after monthly billing to remove the entries for deleted projects from the 
requisition file. 

ARGUMENTS 

path 

is the pathname of the requisition file. The default is the segment, reqfile, in the 
working directory. 
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Name: clear resource, clr 

SYNTAX AS A COMMAND 
clr type STRl ... STRN 
FUNCTION 

specifies that a resource has been manually cleared (degaussed) and should be returned 
to the free pool. 

ARGUMENTS 

type 

is the resource type defined in the RTPT. 

STRi 

is the unique identifying name of the particular resource being cleared. If STR is 
specified in control argument format {i.e.. if it is preceded by a hyphen), then it 
must be preceded by -name or -nm. 

ACCESS REQUIRED 

The use of this command requires execute access to the rcp_sys_ gate. 
NOTES 

The Manual_clear: statement in the RTMF specifies the operation of the resource data 
security features of automatic acquisition and release. If "yes" is specified, volumes of 
the designated type are locked {when released by an accounting owner) in a way that 
does not allow another user to acquire them until the operator certifies that the 
volume has been cleared of all residual information. If "no" is specified (or if the 
statement if omitted), locking does not occur. 
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Name: command usage count, cue 

SYNTAX AS A COMMAND 

cue operation {command_names} {-control_args} 
FUNCTION 

provides a record of the number of times commands are used and the User_ids for 
each invocation of them. The commands to be metered in this way must be listed in 
a segment named command_usage_list_. Usage totals are stored in a segment named 
command_usage_totals_. This command actually performs three operations: it prints 
and clears the meters, adds commands to command_usage_list_, and deletes commands 
from command_usage_list_. 

ARGUMENTS 

operation 

can be one of the following: 

print, pr 

prints (and clears) the metered data (subject to any restrictions the specified 
control_args impose). 

add 

adds commands to the list (command_usage_list_) of commands to be 
metered. Commands added to the list in a single invocation of the "cue add" 
command form a command "group", which can be manipulated as a whole. 

delete, dl 

deletes command groups (see above) from the list of commands to be 
metered. 

command_names 

are long or short names of commands. If given with either the print or delete 
operation, only one command name from each group to be printed or deleted 
need be given, and all the commands in each group so represented are acted 
upon. If no names are given with the print or delete operation, all command 
groups are printed /deleted. Command names (long and/or short) must be given 
with the add operation, and all the names added in a single invocation are added 
as a single group to the list. Short names of commands can only be used with 
the print and delete operations if they were specified with the add operation. 

CONTROL ARGUMENTS 

-all, -a 

prints meters for all the command groups, or deletes all command groups from 
the list. This is the default for the print and delete operations if no 
command_names are given. This control argument cannot be used with the add 
operation. 
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-brief, -bf 

omits column headings from the printout (can only be used with the print 
operation). The default is to print column headings. 

-clear, -cl 

clears the usage counters and user list when meters are printed (can only be used 

with the print operation). It clears the user list even if the -total control 

argument is also specified. 

-first N. -ft N 

prints only the N greatest users of the specified commands (can only be used 
with the print operation). This control argument cannot be used in conjunction 
with the -total control argument. 

-total, -tt 

prints only the total use of the commands in the specified command groups, when 
used with the print operation. When used with the add operation, meters only the 
total usage of commands specified. The default with both of these operations is 
to print /meter the users of the commands as well as total usage. See "Notes" 
below. This control argument cannot be used with the delete operation. 

NOTES 

In order to add and delete commands, and to clear meters, the user must have rw 
access to the command_usage_list_ segment. Otherwise, all users should have r access 
to command_usage_lisi_. and rw access to command_usage_totals_. Both segments are 
found usmg object search rules and most commonly are in >sss (system_library_standard 
directory). If they are not in >sss. a link in >sss points to them. 

For each group of commands added without the -total control argument, this 
command creates a segment named command_name. usage in >sss (or, if a link is there, 
wherever the link points). The user must put the link in >sss before the first usage 
of cue add, since the metering program creates the command_name. usage segment in 
the same directory in which it finds command_usage_list_. The command_name.usage 
segment contains the list of User_ids for those using the commands in the group. 
User_ids are printed in the order of greatest usage. When the -first control argument 
is given, in addition to printing the user count and name for the N greatest users, 
this command prints an additional line giving the user count for "all others." 

At sites using the access isolation mechanism (AIM), only the usage of system_low 
users is recorded. 



2-93 



GB64-00 



command_usage_counl command_usage_couni 



EXAMPLES 



In the following example, assume that no commands are listed in the command_usage_lisl. 
segment. The user adds two commands (in two separate command groups) by typing: 

command_usage_count add set_search_ru 1 es ssr 
cue add enter_abs_request ear -total 

The next time a process is created, those commands can be metered by typing: 



cue print 



The following lines are then displayed: 

USAGE COmAND USER USER 

COUNT GROUP COUNT NAME 

3 set_search_rul es 2 Baker .Mul t i cs 

ssr 1 Green. SysMa i nt 

1 enter_abs_request 
ear 



Note that user count and user name are not provided for the command group added 
with the -total control_arg. 

To delete these commands from the list, the user types: 

cue de I ete -a 1 1 
or the equivalent: 

cue dl 
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Name: compact._maiL.table, salvage.mail_table 
SYNTAX AS A COMMAND 
compact_mai 1_tab1e {size} 

FUNCTION 

used by a system administrator to fix the mail table after it has been damaged or has 
become full. Because the mail table and the person name table (PNT) contain a 
parallel set of entries, any time the PNT needs to be compacted (using salvage.mstb) 
the mail table should also be compacted. When this is done, the old mail table is 
renamed to mail_table.MM/DD.HHMM. 

ARGUMENTS 

size 

specifies the size of the new mail table. If not specified, size defaults to the 
number of used entries (both regular and alias oitries) multiplied by three, which 
is close to optimum for the accessing algorithm. In general, it is b^t to keep the 
mail table the same size as the PNT. If the size specified is not large enough to 
hold the existing entries, an error will be generated. 

NOTES 

This conmiand should be run before the Answering Service is started by the multics 
or startup command. 

salvage_maiLtable is an alternate name. 



Name: compare_jiist 
SYNTAX AS A COMMAND 

compare^mst reel__fdl reel_ld2 {-control^arg} 

FUNCTION 

reads two Multics system tapes (MSTs) and lists all differences between them. 

ARGUMENTS 

reeUidl, reeLid2 

are the reel identification numbers of the two tapes being compared. The reel 
identification number, which is site dependent, can be up to 32 characters long. 
The reel_id can also include a density specification to indicate the density of the 
tape being compared, as in "060341,den-1600*'. 
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CONTROL ARGUMENTS 
-save 

saves the contents of corresponding segments with discrepancies in the user's 
working directory under the names tpl.<segment_name> and tp2.<segment_name>. 
An added segment is saved under the name tp2.<segment_name>. 

NOTES 

Differences in segment headers and the starting address of any inequalities or differing 
lengths of segment contents are noted. Additions, deletions, and moves of segments are 
handled. One can optionally save the contents of differing segments in the user's 
working directory for further detailed comparisons. Any number of collections can be 
handled, but a warning message is' printed if a tape does not end in a collection 
mark. If the active_all_rings_data segment is found on the first tape, a message 
containing the system identifiers of both tapes is printed. 



Name: compute_biil 
SYNTAX AS A COMMAND 
compute__bi ] 1 sat_path pdt_dlr 
FUNCTION 

is used by biller.ec to generate billing information as part of the monthly billing 
process. It totals the usage figures in the PDTs, the miscfile, and the projfile 
segments, and places the totals in the reqfile entry for each project It is also used 
by CTank.ec as part of the daily accounting job to update these same segments. 

ARGUMENTS 

sat_path 

is the pathname of the SAT: >udd>SysAdmin>admin>safe_jxits>saL 
pdt_dir 

is the pathname of the directory containing the PDTs: >safe_pdts. Generally this 
directory contains the copies of the PDTs that were copied from the live PDTs 
during an earlier part of the daily accounting job. 

Entry: compute_bill$update_pdts_from_reqfile satjath pdt__dir 

FUNCT/ON 

This entry is used by the daily accounting job to write the latest per-project 
information from the reqfile, projfile and SAT into the live PDTs. 
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ARGUMENTS 
sat_path 

is the pathname of the SAT: >udd>SysA(lmm>admin>safe_pdts>sat 
pdt_dir 

is the pathname of the directory containing the PDTs: >safe_pdts. 
NOTES 

The reqfile, projfile, and miscfile segments are assumed to be present in the working 
directory, and are implicit inputs to compute^bill. 



Name: console^report 
SYNTAX AS A COMMAND 

console_report {as_log_paths} {-control_args} 
FUNCTfON 

creates and displays metering of terminal usage on the system based on the 
information obtained from the answering service logs. 

ARGUMENTS 

as_log_paths 

are pathnames of answering service logs. The pathnames can be absolute or 

relative. 

CONTROL ARGUMENTS 
-print 

causes a display of the metering on user.outpuL 
-report_reset, -rr 

causes a display of the metering on user.output and resets the metering in the 
data base. 

-reset, -rs 

resets the metmng in the data base. 

-sort 

sorts the data base alphanumerically by terminal answerback identifiers. 
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NOTES 

Control arguments and pathnames can appear anywhere in the command line. They are 
processed from left to right, one at a time. 

The header in the display produced when the -print and -report_reset control 
arguments are used is obtained from the system titles. This header may be too wide 
for the user's terminal and the user may wish to use the file_output command. 

The command creates and stores data into two segments, termseg and termuseg, in the 
current working directory when pathnames of answering-service logs are specified. 
These segments are the data bases that the command expects to find in the current 
working directory when any of the control arguments are used. 

EXAMPLES 

Multics terminal usage 

Period from 08/26/84 1407-9 to 09/25/84 1600.2 



Type 


Count 


Log i ns 


2741 


247 


28 


TN300 


335 


632 


Daemon 


101 


873 


ASCI 1 


1077 


9563 


TELNET 


13 


0 


LA36 


93 


60 


VTIOO 


41 


419 


LA120 


5 


112 



Nologins CPU Connect 

17 0:05 25.22 

48 18:47 604:l8 

4 38:08 4456:06 

1423 531:45 /954:30 

324 0:00 0:00 

11 0:34 15:40 

45 6:10 367:53 

9 2:24 89:51 
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ID Type Location 


Log i ns 


Nol og i ns 




CPU 


Connect 


User 














002 ASCli 


1 


3 


0 


:0k 


3 


:03 


Derek . Mu 1 t i cs 


1 




0 


:0k 


3 


:03 


OOk A^r 1 1 

\J \J n O w 1 1 


z 




n 




1 


:16 


Au 1 i n . Mu 1 1 i cs 


2 




0 


:01 


1 


:16 


405 LA120 


73 


26 


0 


:kG 


/ z> 






JO 




n 


• ^ 1 


53 


:07 


Marcus .Network 


8 




0 


:0k 


6 


:09 


1 nada .Network 


1 1 




0 


:07 


5 


:53 


SBWeber .Network 


9 




0 


:05 


6 


:37 


Ducot . F ] ex^\an 


5 




0 


:01 


3 


:43 


Yip. Network 


1 




0 


:01 


0 


:02 


Fei nstei n. Network 


1 




0 


:01 


0 


:27 


kO> ASCI 1 


2 


0 


0 


:01 


0 


:26 


Stanzel .ARCS 


1 




0 


:01 


0 


:03 


AWhi te.ARCS 


1 




0 


:01 


0 


:2k 


kO> VTIOO 


2 


0 




0:01 


0:38 


HSPP-BASi C.Student 


1 






0:01 


0: 16 


Soley .ARCS 


1 




0:01 


0:23 



etc. 

Type 

is the lerrainal type. 
Count 

is the number of different terminals of that type. 
Logins 

are the number of completed logins. 
Nologins 

the number of logins attempted and not completed. 

CPU 

is the amount of CPU time used. 
Connect 

is the amount of time actually logged in. 

ID 

is an identification number assigned to a specific terminal. 
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Type User 

the terminal type and ID is shown on a heading, followed by a line for each 
user of the terminal giving usage statistics. 

Location 

is not used. 



Name: convert configuration deck 

SYNTAX AS A COMMAND 

conver t_conf i gurat i on_deck ascii_path binary_path 
FUNCTION 

converts an ASCII source form of a configuration deck, as produced by the 
print_configuration_deck command, into a binary {system) form. 

ARGUMENTS 

ascii„path 

is the pathname of an ASCII source form of a config deck. Both labeled and 
unlabeled fields may appear on the config cards. The archive convention is 
allowed. 

binary_path 

is the pathname of the resultant binary form of the config deck. This form is 
compatible with the system config deck. 

NOTES 

This command is intended to be used to perform a level of validation on a proposed 
new ASCII config deck. It may also be used to convert an ASCII config deck into 
the form required by the compare_configuration_deck command. 
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Name: copy as meters 

SYNTAX AS A COMMAND 
copy_as_meter s path 
FUNCTION 

copies the system metering information maintained by as_meter_ from the segment 
>scl>stat_seg into a specified data segment, and resets the index in stat_seg. 

ARGUMENTS 

path 

is the pathname of the copy to be created. 
NOTES 

The statistics are placed in the segment path. 

This command is executed by the crank (in master, ec). which is usually run once each 
day, to enable statistical tools to analyze the system's performance. The system_total 
command uses the segment created by the copy_as_meters command. 



Name: copy deadproc 

SYNTAX 

copy_deadproc {deadproc_name} {-control_args} 
FUNCTION 

sets up a dead process directory in preparation for use by the analyze_multics 
command. It copies a dead process directory specified by deadproc_name into the 
directory under the >dumps>save_pdirs directory. Several hardcore segments needed by 
analyze_multics are also copied into the director}. Two segments are created by the 
copy_deadproc tool, pdir_info and uid_hash_table. These are used by analyze_multics 
when examining a dead process. The dead process directory is renamed to person. pdir, 
where "pdir" is the standard suffix. If person. pdir already exists, it is renamed, before 
copying the new directory, to person. N. pdir, where N=l. If person.l.pdir already 
exists, it is renamed to person.N+l.pdir, and so on. Access to the new pdir is 
determined by the initial dir_acl of the save_pdirs directory. 
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I ARGUMENTS 

I deadproc_name 

I is the name of the dead process directory to be copied. If deadproc_name is not 

j an absolute pathname, the default path is >process_dir_dir>deadproc_name. The 

I names of dead process directories in the >process_dir_dir are of the form 

] person. project. f.tty_name. A name of this form and the full name must be 

j specified. 

CONTROL ARGUMENTS 

j -delete, -dl 

I deletes the original dead process. Status and modify access to the containing 

j directory is needed. If access is lacking, the user is queried about whether to 

I continue copying. 

I -name deadproc_name. -nm deadproc_name 

I specifies the name of the process to be copied. 

I -no_delete, -ndl 

I specifies that the dead process directory is not to be deleted after copying is 

I complete. This is the default. 

j -owner, -ow 

I specifies that access be set appropriately for the owner of the fatal process. This 

I access is status on the dead process directory. 

I ACCESS REQUIRED 

I The use of this command requires access to phcs_. A user can copy his own process 

j if he has "sma" on the save_pdirs directory and access to phcs_. If the dead process 

{ doesn't belong to the process doing the copying, access to the hphcs_ gate is required. 

I When copying terminated processes of a different authorization level than the process 

I doing the copying, access to the system_privilege_ gale is required. 



Name: copy dump 

SYNTAX AS A COMMAND 

copy_dump 

FUNCTION 

copy a dump image taken by BCE out of the DUMP partition into the Multics 
hierarchy. It creates as m.any segments (up to ten) in >dumps as necessary to hold the 
dump image. 
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NOTES 

The name of each segment has the form 

mmddyy . tttt . s . eee 
where 
mmddyy 

is the date the dump was taken. 

tttt 

is the time the dump was taken. 

s 

is a sequence number (0, 1, 2,...9). 
nnnn 

is the dump number assigned when recording this dump. 
Entries copy^dumpSset^dump^um, copy^dumpSsfdn 
Usage: copy_dump$sfdn dmpno 
FUNCTION 

This entry point sets the value of the next dump to be taken by changing the value 
associated with the dump number in the DUMP partition. 

ARGUMENTS 

dmpno 

is the dump number for the next dump to be taken. 
ACCESS REQUIRED 

This command interfaces to hphcs_$copy^dump and to hphcs.$set_fdump_num and 
requires access to hphcs_. 

NOTES 

The DUMP partition is modified only after the last dump taken has been copied. If i 

you attempt to change the dump number before a dump )sa& been copied, an error 
message is returned. 

This conunand does not allow a particular dump to be copied twice; therefore it 
returns an error code if you attempt to recopy a dump. 
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Name: copy mst, cpm 

SYNTAX AS A COMMAND 
cpm reel_idl reel_id2 
FUNCT/ON 

« copies a system tape (BC£/Multics bootload tape) onto another reel of tape. 
ARGUMENTS 
reeLidl 

is the reel identification number of the tape from which information is to be 
copied. The reel identification number, which is site dependent, can be up to 32 
characters long. The reel.id can also include a density specification to indicate 
the density of the tape being copied, as in "060341,den»=1600". 

reeljd2 

is the reel identifier number of the tape onto which the copy is to be made. 



Name: copy__registry 
SYNTAX AS A COMMAND 
I copy__registry pathl {path2} {-control_arg} 
FUNCT/ON 

makes checkpoint copies of RCP Resource Management registries. You can use these 
copies as a basis for the reconstruction of registries destroyed by catastrophic system 
failure. 

ARGUMENTS 
I pathl 

is the pathname of the r^try to be copied. If you give no rcpr suffix, it is 
assumed. You can use the star convention. 

I path2 

is the pathname of the copy to be created. The equals convention is accepted. If 

the suffix rcpr is not given, it is agtumed. If to_path is not supplied, the copy 

will be placed in the working directory and will have the same name as the 
original. (See **Notes.**) 
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CONTROL ARGUMENTS 
-reset 

specifies that the contents of the registry journal are to be discarded after the 
copy operation has been successfully completed. (See "Notes*' below.) 

NOTES 

The RCP Administrator must not copy registries into >scl>rcp (for reconstruction 
purposes or otherwise) except under special session. 

The registry journal contains a record of all operations performed against all registries 
since the time its contents were last reset via the use of the -reset control argument 
described above. Since a successful reconstruction operation depends on the journal 
containing a record of all operations performed since the copies of the registries were 
created, it is important that the -reset control argument only be specified for 
invocations which result in the copying of all registries. The copying of any number 
of registries and the resetting of the journal within one invocation of the 
copy_registry conmiand is performed as an indivisible operation, which guarantees that 
no operations can be performed against any of the r^istries involved until the copying 
operation is complete and the journal has been reset Since this cannot be guaranteed 
between multiple invocations of the copy_registry conmiand, the -reset control 
argument should never be used without copying all active registries. 

When -reset is specified, the journal is reset only if the copy operations are 
completed successfully. 

Copies of system registries are automatically made each night by the system accounting 
facility (crank) using this conunand. 

ACCESS REQUIRED 

This command requires access to the rcp_admin. gate. 
EXAMPLES 

To make checkpoint copies in the current working directory of all RCP Resource 
Management entries and discard journal entries made since the last checkpoint, type: 

copy_registry ** -reset 
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Name: create__daemoii^queues, cdq 
SYNTAX AS A COMMAND 
cdq {path} {-control_args} 
FUNCTION 

creates the I/O daemon queues. It determines which queues to create by examining 
the iod_tables segment 

ARGUMENTS 

path 

is the pathname of an iod_tables segment created by the iod_tables_compiler. The 
queues are created in the containing directory of path, using the request types 
specified by the iod.tables segment This argument is optional. 

CONTROL ARGUMENTS 

-directory path, -dr path 

queues are created in the directory whose pathname is path. This control 
argument is provided for testing purposes only; normally, it should be omitted. 
When not specified, the queues are created in the >daemon_dir_dir>io_daemon_dir 
directory. Iliis argument may not be given with a path specification. 

-reset_access 

resets the ACLs on each queue to the default value, if the queue already exists. 
NOTES 

The I/O daemon tables segment, called iod_tables, is expected to be found in the 
same directory in which the queues are to be created. For each request type defined 
in iod.tables, one to four queues are created, depending on the maximum number of 
queues for that request type (as defined in iod_tables). The name of each queue is of 
the form XXX_N.ms where XXX is the associated request type name and N is the 
priority number of the queue. The ms suffix indicates that each queue is a message 
segment 
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Name: create mail table 

SYNTAX AS A COMMAND 
create_mai l_table 
FUNCTION 

used by system administrators to create the initial mail table. The mail table is 
initially populated with information taken from the person name table (PNT). 

ACCESS REQUIRED 

The user must have e access to the gate mail_table_priv_. r access to the PNT, and 
sma access to >site>mail_system in ring-2. In addition, the access class of the mail 
table will be the current authorization of the creator, so this user should be logged in 
at system_low (this may be ignored if the site does not use multiple AIM levels): the 
command will attempt to set dir and seg privileges, in which case the mail table will 
be created at system low, regardless of the authorization of the creator. 

NOTES 

Generally, this command should only be needed once, the first time the system is 
booted when it is delivered, or when the site first upgrades to MR10.2 (or a later 
release. The mail table was first implemented in MR10.2). It must be used after the 
PNT has been created, but before the system is brought up for regular service: the 
safest way is to run it before the Answering Service is started. 



Name: create pnt 

SYNTAX AS A COMMAND 

create_pnt pathname {-size N} 

FUNCTION 

create a pnt segment. 

ARGUMENTS 

pathname 

specifies the pathname of the pnt segment. If the ".pnt" suffix is not included in 
the segment name, it is automatically added. 
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CONTROL ARGUMENTS 
-size N 

specifies that the pnt is to be created with sufficient space for N entries, where 
N is a decimal number. (A user registration uses one entry and an alias uses one 
entry.) 

ACCESS REQUIRED 

This command requires access to the pnt_fs_gate_. 
NOTES 

This command is automatically executed by the accounting startup exec_com 
(accl_start_up.ec) when a new Multics site is initialized. This command is useful for 
administrators who want to create an alternate pnt for testing purposes. 



I Name: create urf 

I SYNTAX AS A COMMAND 
I create_urf path {-size N} 
I FUNCTION 

I creates a user registration file. 
I ARGUMENTS 

j path 

I specifies the pathname of the urf segment. 
I CONTROL ARGUMENTS 
-size N 

specifies that the urf is to be created with sufficient space for N entries, where 
N is a decimal number. A user registration uses one entry. 

I NOTES 

I This command is normally executed by the accounting startup exec_com (acct_start_up.ec) 
i when the site is initialized. 
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Name: cv cmf 

SYNTAX AS A COMMAND 

cv_cmf cmf_path {-contro1_args} 

FUNCTION 

converts an ASCII channel master file (CMF) into a binary channel definition table 
(CDT). The binary table can be installed using the install command. 

ARGUMENTS 

cmf_path 

is the pathname of the channel master file. If path does not have a suffix of 
cmf, one is assumed. However, the suffix cmf must be the last component of the 
name of the source segment. The channel master file is normally located at | 
>udd>SysAdmin>admin>CMF.cmf. | 

CONTROL ARGUMENTS 

-brief, -bf 

uses short form of error messages. 

-long, -Ig 

uses long form of error messages. 

-severity N, -sv N 

causes error messages whose severity is less than N (w-here N is 0, 1. 2, 3, or 4) 

not to be written to the user_output switch. If this control argument is not 

specified, a severity level of 0 is assumed (i.e., all error messages are written to 
the user_output switch). 

NOTES 

If no control arguments are given, each error message is printed in long form the 
first time it occurs and in short form thereafter. 

The converted channel master file is given a name corresponding to the entryname of 
the source segment, with the cmf suffix replaced by cdt. It is placed in the working 
directory. 
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LIST OF SEVERITY VALUES 

The cv_cmf command associates the following severity values to be used by the 
severity active function: 



Value Meaning 

0 No compilation yet or no error. 

1 Warning. 

2 Correctable error. 

3 Fatal error. 

k Unrecoverable error. 

5 Could not find source. 



I 

I Name: cv_dmcf 

I SYNTAX AS A COMMAND 

I cv dmcf path 

j FUNCTION 

I converts a configuration source file into a DMS configuration table, used to shape the 

I run-time environment at DMS initialization. The source file is an ASCII segment 

I composed of source statements as described below. The table must be installed by the 

I administrator in the per-AIM directory to enable the DM daemon to boot DMS. 

I ARGUMENTS 

I path 

j is the pathname of the configuration source file. The file must have the suffix 
I .dmcf as part of its entryname. The suffix is added if not present. 

j NOTES ON SOURCE STATEMENTS 

I Source file statements take the form <keyword:> <value;>. Any number of statements 

I can be specified in any order, but a keyword can only appear once. The last 

I statement must be <end:>. 



2-112 



GB64-00 



cv_dmcf 



cv_dmcf 



LIST OF KEYWORDS 

system_before^ournal_size N 

sets the size of the system default before journal to N control intervals. The 
number of transactions processing concurrently, their average time, and rate of 
modification are factors to be considered in establishing optimal journal size. 
Analyzing metering information and other performance criteria will enable you to 
fine-tune this value over time. The default is 4000. 

max_processes N 

sets the maximum number of processes that can use Data Management concurrently 
to N. Unless there is reason to restrict th? number of users, this value should be 
keyed to the number of processes that can log in to the AIM classification being 
configured for DMS. The default is v/hatever the load control for a given 
Multics configuration can support, up to 256. 

max_transactions N 

sets the maximum number of transactions that can be in progress concurrently to 
N. Ideally, this value should equal the number of processes that can use DMS. 
The default is 128. 

default_before_journal path 

specifies the location of the system default before journal. Path is composed of 
one or both of dir=DIR and entry=ENTRY. If both values are specified, they are 
separated by a comma. DIR is either an absolute pathname of the directory in 
which the default before journal is to reside, aim_dir {the per-AIM directory of 
the DMS being initialized), or bootload„dir (the DMS per-bootload directory). 
ENTRY is either the entryname of the default before journal or system_default.bj. 
The default is dir=aim_dir,entry=system_default.bj and is the recommended location 
of the system default before journal. 

idle_timeout N 

sets the frequency of wakeup calls to the DM daemon to every N minutes. Upon 
receiving a wakeup call, the daemon performs its caretaker function of adjusting 
unfinished transactions. Independent of this mechanism, the daemon is on call 
(through process termination notifications, for example) to perform this function 
as needed. The idle timeout is provided to ensure that the daemon is periodically 
stirred to action in the absence of any other notification. The default is 15. 

begin_shutdown_delay N 

sets the delay between the user warning and begin shutdown stages of DMS 
shutdown to N minutes. The default is 5. 

user_shutdown_delay N 

sets the delay between the begin shutdown and user shutdown stages of DMS 
shutdown to N minutes. The default is 5. 

user_bump_delay N 

sets the delay between the user shutdown and user bump stages of DMS shutdown 
to N minutes. The default is 5. 
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daemon_logout_delay N 

sets the delay between the user bump and daemon logout stages of DMS 
shutdown to N minutes. The default is 5. 

prev_bootload_status list 

determines the disposition of the previous DMS per-bootload directory when 

initializing DMS in the same AIM directory. Options in the list are separated by 
commas; they are as follows: 

hold 

specifies that the previous bootload directory is to be renamed and retained 
(usually for debugging or test purposes). The default is '^hold. 

adopt 

specifies that if there is already a DMS bootload directory for the current 
Multics system bootload, the DM daemon should take it over. The 
implication is that the deamon process for that DMS invocation died. The 
default is adopt. 

recover 

specifies that recovery of DM files associated with the previous DMS 
invocation should be attempted. The default is recover. 

recovery _check_mode 

specifies that before journals are to be searched completely for uncommitted 
transactions. The implication is that there is a discrepancy between the 
number of indicated and actual transactions requiring recovery. This is a 
debugging tool, to be turned on only at the direction of Multics System 
Support . The default is ^recovery_check_mode. 

The default values in effect for these options are the recommended 
operational settings. 

current_bootload_enable STR 

specifies whether to force enabling of the current invocation of DMS. despite 
being unable to recover from a crash of the previous invocation. STR is force to 
enable DMS whether or not there are errors in recovery, or force to enable 
DMS only if recovery was successfully completed. A value of force should be 
specified only at the direction of Multics System Support. The default is ^ force. 

log_proc_terms STR 

specifies whether the DM daemon is to log each occurrence of adjusting a 
transaction because the owner process has died. Some sites may consider this type 
of notification benign and wish to turn it off to conserve log space. STR can be 
on or off. The default is on. 
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NOTES 



The output from this command is a segment table that takes the same entryname with 
the suffix .dmct. To install this table in the per-AIM directory, use the copy 
command, giving the new segment the name dm_configuration. See the section entitled 
"Data Management Administration" in the Multics System Administration Procedures 
manual. Order No. AK50, for details on installing and bringing up Data Management 
on Multics. 



You should not attempt to install dm_configuration in a per-AIM directory when the 
DM daemon is initializing the system. A lockword is set in dm_configuration to 
prevent multiple daemons from attempting initialization with the same segment at the 
same time. If the copy overlaps initialization, this protection may be subverted, with 
unpredictable results. As a safeguard, perform the copy only when the daemon is 
logged out. 

EXAMPLES 



The sample source file is presented below as a guide to proper formatting. It is not 
intended as a suggested DMS configuration. 

max_processes : 100; 

max_transact i ons : 100; 

system_bef ore_journa l_s i ze: 2000; 

def aul t_bef ore_journa 1 : di r=bootload_di r; 

beg i n_shutdown_del ay : 10; 

user_shutdown_de] ay : 10; 

prev_boot 1 oad_s tatus : hold, ^adopt , recover y_check_mode ; 
log_proc_terms : off; 
current_boot load_enable: force; 
end ; 



Name: cv pmf 

SYNTAX AS A COMMAND 

cv_pmf pmf_path {-control_args} 

FUNCTION 

converts an ASCII project master file (PMF) into a binary project definition table 
(PDT). 
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ARGUMENTS 
pmf_path 

is the pathname of the PMF. If path does not have a suffix of pmf, one is 

assumed; however, the suffix pmf must be the last component of the name of the 
source. The PMF is normally stored in the hierarchy of the project administrator. 

CONTROL ARGUMENTS 

-brief, -bf 

prints error messages in the short format. 

-long. -Ig 

prints error messages in the long format, 
-severity N, -sv N 

causes error messages whose severity is less than N (where N is 0, 1. 2, 3. or 4) 
not to be written to the user_output switch. If not specified, a severity level of 
0 is assumed; i.e.. all error messages are written to the user_output switch. 

NOTES 

The newly converted PDT is placed in the current working directory. The entryname 
of the new PDT is the same as the entryname of its source PMF. with the pmf 
suffix replaced by pdt. This command associates the following severity values to be 
used by the severity active function: 



Value Meaning 

0 No compilation yet or no error. 

1 Warning. 

2 Correctable error. 

3 Fatal error. 

k Unrecoverable error. 

5 Could not find source. 



EXAMPLES 

cv_pmf >udd>Proj ect_i d>proj f i 1 e 

converts the PMF >udd>Project_id>projfiie.pmt and creates a PDT named projfile.pdt 
in the project administrator's working directory. 
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Name: cv prt rqti 

SYNTAX AS A COMMAND 
cv_prt_rqti path {-control_arg} 
FUNCTION 

converts an ASCII printer request type info source segment into a printer request type 
info segment (rqti segment) for use by the I/O daemon. The newly converted rqti 
segment is placed in the current working directory. The entryname of the new rqti 
segment is the same as the entryname of its source segment without the rqti suffix. 
The ASCII source segment is created by the administrator. See the Multics System | 
Maintenance Procedures manual. Order No. AM81 for additional information on the | 
creation of rqti source segment. j 

ARGUMENTS 

path 

is the pathname of the request type info source segment. The source segment 
must have a rqti suffix, although the suffix may be omitted in the command 
invocation. 

CONTROL ARGUMENTS 

-brief, -bf 

prints error messages in the short format. 

-long. -Ig 

prints error messages in the long format. This is the default. 
EXAMPLES 
The command line: 

cv_prt_rqti pr i nter_i nf o. rqt i 
creates a request type info segment named printer_info in the working directory. 



2-117 



GB64-00 



cv_rimf 



cv_rtmf 



Name: cv rtmf 

SYNTAX AS A COMMAND 

cv_rtmf rtmf_path {-control_args} 

FUNCT/ON 

converts an ASCII resource type master file (RTMF) into a binary resource type 
description table (RTDT). The binary table is installed using the install command. If 
the user has made any errors in the RTMF, this command prints error messages while 
performing the conversion. 

ARGUMENTS 

rtmf_path 

is the pathname of the resource type master file. If path does not have a suffix 
of rtmf, one is assumed. However, the suffix rtmf must be the last component 
of the name of the source segment. The ASCII RTMF is normally located at 
>udd>SysAdmin>admin>RTMF. 

CONTROL ARGUMENTS 

-brief, -bf 

prints short form of error messages 

-long. -Ig 

prints long form of error messages 

-severity N, -sv N 

causes error messages whose severity is less than N (where N is 0, 1, 2, 3, or 4) 
not to be written to the ,user_output switch. If this control argument is not 
specified, a severity level of 0 is assumed (i.e,, all error messages are written to 
the user_outpui switch). 

NOTES 

If no control arguments are given, an error message is printed in long form the first 
time it occurs, and in short form thereafter. 

The converted resource type master file is given a name corresponding to the 
entryname of the source segment, with the rtmf suffix replaced by rtdt. It is placed 
in the working directory. 

The syntax of an RTMF is described in the System Administration Procedures 
manual. Order No. AK50. 
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EXAMPLES 

The cv_rtmf command associates the following severity values to be used by the 
severity active function: 



Value Meaning 

0 No compilation yet or no error. 

1 Warning. 

2 Correctable error. 

3 Fatal error. 

k Unrecoverable error. 

5 Could not find source. 



Name: daily summary 

SYNTAX AS A COMMAND 

da i 1 y_summary {-control_args} 

FUNCT/ON 

prints a summary of system usage for the current billing period and a list of projects 
with overspent accounts. It also places a flag in the SAT for each project that has an 
overspent account or has passed its termination date. 

CONTROL ARGUMENTS 

-nocutr 

do not print a list of projects to be cutoff, 
-nosat 

do not flag SAT entries, 
-nosum 

do not print a system usage summary, 
-warn 

for all projects to be cutoff, use a warning flag that permits users to login. 
NOTES 

The segments reqfile and smf.cur.sat are assumed to be present in the working 
directory and are implicit inputs to the daily_summary command. 
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This command writes the system usage of each project in the reqfile on the sumry 
I/O switch. The usage figures are cumulative from the time that billing was last run. 
It also writes a list of projects that have run out of funds or are past the termination 
date and flags their SAT entries on the cutrpt I/O switch. 

The information about the closeness of a project to its limits, that is used to decide 
whether to print a cutoff warning message when users on the project log in, is placed 
in the SAT by this command. 

The cutrpt and sumry I/O switches must be attached by the caller. 

EXAMPLES 

The command line: 

da i 1 y_summary -nosum -nocutr 

should be used before each installation of the SAT. to update cutoff information. The 
entries in masler.ec that install the SAT do this. 



Name: deactivate seg 

SYNTAX AS A COMMAND 

deact i vate_seg path {-control_arg} 

FUNCTION 

allows you to deactivate a segment or directory. 

ARGUMENTS 

path 

is the pathname of the segment or directory to be deactivated or a segment 
number. 

CONTROL ARGUMENTS 

-force, -fc 

deactivates the segment or directory, if possible, by using the highly privileged 
demand_deactivate entry. 

ACCESS REQUIRED 

This command requires access to the phcs_ gate; if you use -force, it requires access 
to the hphcs_ gate. 
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NOTES 

If you don't supply -force, the segment or directory is only deactivated if all 
processes connected to it have the allow_deactivate attribute set (see the 
change_kst_attributes command). If you give -force, the segment is deactivated unless 
its entry hold switch is set and the directory is deactivated unless it has active 
inferiors. 



Name: debug__fnp, db__fnp 

SYNTAX AS A COMMAND 
db_fnp {request} 
FUNCTION 

is a debugging aid intended to be used by FNP software developers and in FNP dump 
analysis. You can use it to patch or dump memory in a running FNP, to examine a 
dump from a crashed FNP or a core image segment before it is loaded, to set 
breakpoints in a running FNP, and to display symbolically FNP control blocks, 
buffers, etc. 

ARGUMENTS 

request 

is the first request(s) to be executed. Once the initial request(s) is completed, 
debug_fnp reads request lines from user^input Bach line can contain multiple 
requests, separated by semicolons. If an error occurs in any request, the remaining 
requests on that line are not be executed. You can abort any request by typing 
"quit" followed by a "pi" (program_interrupt). 



NOTES ON debug Jnp MODE SELECTION 

This command can operate on a running FNP, a dump segment, or a core image 
segment; with few exceptions, most requests, work the same regardless of the selection. 
When first invoked, the command is set up to examine the first configured FNP. You 
can switch between dumps, core images, and running FNPs at any time. 

LIST OF MODE SELECTION REQUESTS 

fnp 

Usage: fnp tag 

selects a running FNP. where tag can be "a". "T)". "c**. "d", "e", "f", "g". or "h*'- 
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image 

Usage: image path 



selects a core image, where path is the Multics pathname of a segment containing 
the core image. Core image segments and dump segments have a different format, 
so the image and dump requests are not interchangeable. The pathname on this 
request can also be a stamame, provided it matches only one entry in the 
directory specified. 

dump 

Usage: dump path 

selects a dump, where path is the Multics pathname of a segment containing the 
dump. Core image segments and dump segments have a different format, so the 
image and dump requests are not interchangeable. The pathname on this request 
can also be a stamame, provided it matches only one entry in the directory 
specified. 

In most cases, it is not necessary to know the pathname of the dump to be 
examined, as special requests are provided for selecting dumps. 



dumps 

Usage: dumps 

lists all the dumps currently in the dump directory. The default dump directory 
is >dumps. 

dump_dir 

Usage: dump_dir {path} 

changes the default dump directory, where path is the pathname of the new dump 
directory. If you omit "path," the name of the current dump directory is printed. 

last_dump 

Usage: last_dump 

selects the latest dump. 

prev_dump 

Usage: prev_dump 

selects the next earliest dump. You can use this request to peruse any or all the 
dumps in the dump directory, going in either direction. You can use it repeatedly 
as long as there are more dumps. 
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next_dump 

Usage: nexudump 

selects the next latest dump. You can use this request to peruse any or all the 
dumps in the dump directory, going in either direction. 

select_fnp 

Usage: select_fnp tag 

selects which FNP in the dump is examined, when dealing with a dump that 
contains multiple FNPs, such a BOS fdump; tag can be "a", "b", "c". "d". "e", 
"f". "g". or "h". 

what 

Usage: what 

prints the fnp tag or the pathname, to find out what FNP, dump, or core image 
is selected. 

NOTES ON EXPRESSIONS 

Many of the following requests take numeric arguments such as addresses, lengths, etc. 
You can express any of these arguments as a generalized FNP expression. Expressions 
can be arbitrarily complex, coniaMng "C, «+^, and with their 

normal meanings and precedence. The sjrmbol '*|*' is synonymous with "+", as in 
module I offset You can specify indirection by ",*", following the address to indirect 
through. Numeric constants are interpreted as octal unless they are followed by a 
in which case they are decimal. You can use for the current location counter, 
which is generally the last address used in a display or patch request You can also 
use many common FNP symbols, including all fields in the system comm region, the 
hardware conun region, the software conun region, and the TIB. (Before you can use 
TIB, hwcm, and sfcm addresses, establish the addresses of these control blocks. See 
the line and set requests.) A symbol can also be any opblock nmemmonic, the name 
of any FNP object module, or a machine instruction (enclosed within apostrophes). In 
addition, you can define user symbols. For example, 

hsIaiSOO 
t. icp,* 
*+30 

tib|U,*+10 
goto 

'Ida 0,2,b.O' 

cax3 (apostrophe net needed if there is no operand) 
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LIST OF FNF MEMORY DiSPLAr REQUESTS 
display, d 

Usage: display address {length} {mode} 
d address {length} {mode} 

displays the contents of FNP words, where address is the starting address, length 
is the number of words, and mode is the display mode. The symbol "*" is set to 
the address specified. You can use the following display modes: 

octal , oct 
character, ch 

address, addr (in form module|of f set) 
clock, ck {k FNP words as a Multics clock) 
instruction, Inst (355 instruction format) 
opblock, op (pseudo-opblock format) 
decimal, dec 
bit 

ebcdic, ebc 

If you omit length, it defaults to 1 unless address is a predefined FNP symbol, in 
which case the appropriate length for that symbol is used. Similarly, if you omit 
mode, octal is used unless address is a predefined FNP symbol, in which case the 
mode appropriate for that symbol is used. 

buffer, buf 

Usage: buffer {address} {mode} {-brief, -bf} 
buf {address} {mode} {-brief, -bf} 

displays a buffer, where address is the address of the buffer, mode is the mode 
to display it in (see the display request), and -brief means display only the first 
two words of the buffer. If you omit address, the next buffer pointer from the 
previous buffer displayed is used. If you omit mode, character mode is assumed. 
If you omit -brief, the entire buffer is displayed. The length is determined 
automatically by reading the buffer header. 

buffer_chain, bufc 

Usage: buffer_chain {address} {mode} {-brief, -bf} 
bufc {address} {mode} {-brief, -bf} 

displays a buffer chain. 
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block, blk 

Usage: block {address} {-offset, -o offset} {-length, -1 length} 
blk {address} {-offset, -o offset} {-length, -1 length} 

displays a control block at the address specified. Use this request if the data 
being displayed is in the form of threaded control blocks. The default offset to 
the forward pointer in the block is 0. The default block length is eight words. 
If you specify no address, the next block in the chain is displayed (using the 
forward pointer from the previous block). 

block_chain, bike 

Usage: block_chain {address} {-offset, -o offset} {-length, -1 length} ■ 
bike {address} {-offset, -o offset} {-length. -1 length} 

displays the entire chain of control blocks until one with a zero forward pointer 
is encountered. Use this request if the data being displayed is in the form of 
threaded control blocks. The request follows the threads in the buffer chain, 
displaying each buffer. The default offset to the forward pointer in the block is 
0. The default block length is eight words. If you specify no address, the next 
block in the chain is displayed (using the forward pointer from the previous 
block). 



Usage: flags address {type} 

shows the setting of individual bits. Use this request if the data being displayed 
is a word of flags. The argument address is the the address of the word 
containing flags; type can be: 

t.stat tib status word 

t.flg first tib flag word 

t.flg2 second tib flag word 

t.flg3 third tib flag word 

sf.fig hsla sfcm flags 

istat interpreter status word 

hs.l first word of hsla liardware status 

hs.2 second word of hsla hardware status 

If you omit type, it is assumed to be the same as "address,'* which then must be 
one of the items in the above list. The flags are listed by name, as they appear 
in the macros.map355 source file. You can use the explain request for help on 
unfamiliar names. Occasionally, the value of a flag word is known (from a trace, 
for example), without knowing an address of it. In this case, you can use the 
following form: 

flags "expression type 

where expression is any valid expression and type is one of the types shown 
above. 
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LIST QF FNP MEMORY-PATCHING REQUESTS 



patch 

Usage: patch address argl... {argn} 

patches the contents of FNP memory, where address is the starting address to 
patch and argi represent patch data. Each argi can be an expression representing 
the value to be stored in one FNP word or a character string in quotes (which 
can contain more that one word of data). The total number of words patched 
cannot exceed 32. Before the patch is applied, the effects of the patch are 
displayed (old and new contents of every word) and you are asked to verify that 
the patch is correct The symbol is set to the address specified. Examples of 
patch requests are: 

patch 43102 203456 -1 2 
patch .crver "3.1x" 



patch Ctrl 
patch hsia 



li*00 goto Ctrl 1 1600 
1541 'tze 13' cax3 'Ida 0,2,b.1' 



A shorthand form of this request is 
=argl . . . {argn} 



which is equivalent to 

patch * argi ... {argn} 



set_flag 

Usage: set_flag flag_symbol 

sets the bit associated with the flag^symbol specified in the appropriate word. 
Use this request to manipulate individual flag bits in words of flags. 

clear_flag 

Usage: clear_f lag flag_symbol 



clears an individual bit Use this request to manipulate individual flag bits in 
words of flags. This request is not an indivisible operation; this means if other 
flag bits in the word are dynamically changing, this request may change their 
value if they happen to have been changed between the time the word was read 
and when it was rewritten. 



LIST OF DUMP ANALYSIS REQUESTS 



The following requests are valid only when using debug^fnp on a dump. 
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why 

Usage: why 

finds out the cause of a dump. It prints the type of fault that caused the crash 
and, if the crash was caused by a "die" opcode in the FNP, interprets the reason 
for the crash. 

regs 

Usage: regs 

prints the contents of all machine registers at the time of the fault. 
calLtrace 

Usage: call_trace address {-long, -Ig} 

starts at the address specified and perform a backward trace of all subroutine 
calls. The subroutine must be as defined by the map355 "subr" macro. If you 
give -Ig, the registers saved at each subroutine level are also printed. You can 
also use this request on a running FNP, but the information is probably changing 
too fast for the request to be useful. 

LIST OF FNP TRACE TABLE REQUESTS 

A running FNP or a dump contains a trace table of the most recent events occurring 
in the FNP. 

print^trace 

Usage: print_trace {start} {count} 

displays the trace table, where start indicates the starting trace message and count 
is the number of messages to display. If you supply no arguments, the entire 
trace table is printed. If you give no count, the trace table is displayed from the 
starting point specified to the end. If the start number is positive, it is coimted 
from the oldest message; if negative, it is counted from the most recent For 
example, 

print_trace 200. 
skips the 199 oldest entries and print the rest 

print_trace -50. 

prints the 5C most recent messages. 

Note that the start and count like all other numeric values, are octal unless followed 
by a decimal point Printing the trace table of a running FNP is only meaningful if 
tracing has be^ suspended; otherwise the table is changing too fast to be interpreted. 
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stop_trace 

Usage: stop_trace 

suspends tracing in a running FNP. 

start_trace 

Usage: start_trace 

restarts tracing in a running FNP. 

Tracing can also be stopped and started with some of the breakpoint requests 
explained below. 

Which modules in the FNP are traced is determined by the trace mask, kept in FNP 
memory, 

trace_mask 

Usage: trace_mask {modules} 

examines or updates the trace mask. If you give no modules, trace_mask displays 
and interprets the current trace mask. If you give modules, they represent 
modules to be added to, or deleted from, the current mask. Specify the module 
as "name" or "+name" to set the tracing bit for the module and as "-name" or 
"'^name" to turn off the corresponding bit In addition, you can specify all and 
none. For example, 

trace_mask hsla ^dia -util 
turns on tracing for hsla_man and turn off tracing for dia.man and utilities. 

Turning tracing on for a module for which tracing was not enabled when the 
core image was bound has no efect. 

NOTES ON FNP BREAKPOINT FACIUTY 

The control table interpreter in the FNP allows breakpoints to be set in the 
interpreted control tables. A breakpoint causes the line encountering it to stop 
execution in the interpreter until you give a request to restart it 

You can use breakpoints only if the module breakpoint_man is included in the core 
image. 

Breakpoints are often a useful tool, but be careful in their use. The following points 
are important* 

1. Breakpoints can only be set in interpreted opblocks. They cannot be set at 
machine instructions. 
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2. While at a break, the line is executing an opblock equivalent to 

wait 0,0,0 

followed by no status blocks. This means that timers can run out unnoticed, 
status can be ignored, hangups can be missed, etc. For this reason it may be 
difficult to restart a channel after a breakpoint 

3. Breakpoints cannot be set at subroutine levels where waits would be illegal. 

4. Breakpoints cannot be set when a restart may execute a wait opblock. 

5. Breakpoints cannot be set at a status opblock. 

6. If a breakpoint is set at a wait opblock, it must be reset before the line is 
restarted. In addition, a breakpoint cannot be set at a wait if any channels are 
currently waiting at that block. 

7. Control tables that use local internal variables (as opposed to variables in the TIB 
extension) cannot depend on these variables being preserved during the break 
imless other channels that may use the same control tables are not running. 

8. No notice is given when a channel encounters a breakpoint The list__break request 
lists all breakpoints and shows what diannels are stopped at each one. 

LIST OF FNP BREAKPOINT FACILITY REQUESTS 

set_break, sb 

Usage: set_break address -line- {-stop_trace} 
sb address -line- {-stop_trace} 

sets a breakpoint at the address specified. If you give a tty channel, the 
breakpoint applies to that line only, and any other channel encountering the 
breakpoint continues execution; otherwise, the breakpoint applies to any channel 
that encounters it If you supply -stop_trace, the FNP automatically suspends 
tracing if any channel stops at that breakpoint 

reset_break, rb 

Usage: reset.break address, rb address 
reset_break -all, rb -all 

resets a break at the address specified. Any lines stopped at the break are not 
automatically restarted. If you give -all, all breaks are reset 
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start, sr 

Usage: start line {address} {-reset} {-start_trace} 
sr line {address} {-reset} {-start_trace} 
start -all, sr -all 

restarts the line specified. If you supply an address, the line restarts at the 
address given, instead of where it was stopped. If you supply -reset, the break is 
reset before the line is started. If you supply -start_trace, tracing resumes as the 
line is restarted. If you supply -all, all lines at breakpoints at the time you issue 
the request are restarted. 

list_break, lb 

Usage: list_break 
lb 

lists all FNP breakpoints and the channels stopped at each. 
LIST OF PERFORMANCE ANALYSIS REQUESTS 

The FNP software periodically samples the instruction counter to determine whether 
the FNP is running or idling. 

idle_time 

Usage: idle_time (-reset, -rs} 

prints the percentage of time the FNP has been idling since bootload or the last 
time you invoked the request with -rs. 

sample_time 

Usage: sample_time {new_time} 

prints or sets the sampling interval used by the FNP for metering data, where 
new.time is the new sampling interval in milliseconds (between 1 and 1000). If 
you supply no argument, the current sampling interval is printed. (Default when 
the FNP is booted: SO milliseconds) 

You can collect more detailed information on FNP usage by configuring the 
module "ic.sampler" in the FNP core image. This module periodically samples the 
instruction counter (at the rate set by sample_time) and adds 1 to a bucket, 
which represents a small range (typically 16) of FNP addresses. With this data 
you can determine with some precision where the FNP is spending its time when 
it is running. 
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ic_sample 

This request is only accepted if the ic_sampler module is configured in the FNP. 
It has the following options: 

Usage: ic_sample start 

starts the ic sampling feature. Sampling is normally disabled when the FNP is 
booted. 

Usage: ic_sample stop 
stops ic.sampling. 
Usage: ic_sample reset 
zeroes all the sampling buckets. 
Usage: ic_sample module 

prints a table showing each module in the core image and what percentage of 
samples collected occur in that module. 

Usage: ic_sample histogram, hist {fraction} 

prints a histogram showing each bucket address that has data and the percentage 
of nonidle time that bucket represents. The fraction must be a floating point 
number between 0.0 and 1.0. With this option, the histogram only contains the 
most frequently used buckets. Enough buckets are printed so that the fraction 
specified of the total data collected is printed. For example, if the fraction is .9, 
10% of the data collected is not displayed by discarding infrequently referenced 
buckets. This option is useful in deleting "noise** from the histogram. 

LIST OF MtSCELLANEOUS REQUESTS 



Usage: line {line} 

locates the TIB, software comm region, and hardware conmi region of the line 
specified. Once these addresses are set, you can reference fields in these control 
blocks by name in any expression in other requests. You can specify the line 
either in Multics form \a,h012) or as an FNP line niimber (1014). If you give no 
line, the name of the current line is printed. If the line selected is not on the 
current FNP, the proper FNP is selected automatically. You can specify the line 
as -login_channel, in which case your login channel is selected. 
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buffer_status, bstat 

Usage: buffer_status {-brief, -bf} 
bstat {-brief, -bf} 

prints a table showing each line and how much buffer space in the FNP it is 
using. If you use -bf, only summary information is printed. 

set 

Usage: set symbol value 

sets a symbol, where symbol is "*", "tib", "hwcm". "sfcm", or any user-defined 
symbol. Setting control block addresses (tib, hwcm, sfcm) is more easily done 
with the line request, but can be manually done with this request in case internal 
FNP tables have been damaged. Note that setting any of these control block 
addresses has no effect on the current value of other control blocks. Setting 
is also done by any dump or patch request Once set, a symbol can be used in 
any expression in any other request 

map 

Usage: map 

displays a list of modules, their addresses in the core image, and their dates of 
compilation. 

convert_address, cva 

Usage: convert_address {addressl} ... {addressn} 
cva {addressl} ... {addressn} 

displays the address in any other meaningful forms that can be derived. For 
example, octal values are converted to module | offset, and vice versa. 

explain 

Usage: explain syml {sym2} ... {symn} 

finds the explanation of any FNP symbol (usally the output of a flags or 
convert_address request), where symi are symbols to be explained. It prints the 
comment from the line in macros.map3S5 that defined the symbol. 

e 

Usage: e command_line 

executes any Multics command by passing "command_line" to the conunand 
processor. 

quit, q 

Usage: q 

exits from debug^fnp. 
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Name: defme__work ^class, dwc 

SYNTAX AS A COMMAND 

dwc pct_wcl {pct_wc2. . .pct_wcn} 

FUNCTION 

assigns percentages of CPU time to various work classes independently of what is 
specified in the master group table (MGT). 

ARGUMENTS 

pct_wci 

is the percentage of CPU time to be assigned to the ith work class. If pct_wci is 
zero, the ith work class is not defined. If you don't specify pct_wci (there is no 
ith argument), the ith work class is not defined. 

NOTES 

The effect of dwc is temporary, since the answering service defines the work classes 
specified in the MGT at the next shift change or the next time the operator issues 
the "maxu auto" command. The percentages are ignored if the scheduler is in deadline 
mode. 

The percentages specified are normalized to a sum of 100% by the hardcore scheduler. 

This command does not allow work classes defined in the MGT to be undefined; it 
can create, however, undefined work classes. No ch^ges made by dwc are recorded in 
the MGT. No work class containing active processes can be undefined. You can use 
dwc to change all work classes out of real-time mode, although you can also use the 
tune_work_class command after dwc to change some work classes mto real-time work 
classes. 

You can use this command in the following cases: 

1. While testing or tuning the priority scheduler, to rapidly change the percentages 
assigned to different work classes. 

2. If the percentages specified in the MGT are temporarily out of balance, to handle 
the transient condition gracefully without installing a new MGT. 

3Trs. octoWi^slh «t5AC^!>1 '>••• ad ^f>C wr»t*V ^Iflcc-ac tjt tK*> «»f?««^<r»ilet»»o*oir'c Aivn^A*\t\r^ ffs-r 

the duration of a shift You can then use the set_work_class command to move 
certain processes into the new work class. 
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EXAMPLES 

The following three command lines are equivalent and define work classes 1, 2, 3, 4, 
and 6, each with 20% of available CPU time. 

dwc 20 20 20 20 0 20 

dwc 20 20 20 20 0 20 0 

dwc 1 1 1 1 0 1 

Assume work classes 1, 2, and 3 already exist with 50%, 30%, and 20% of CPU time, 
respectively. To temporarily create a special work class and give it approximately 10% 
of available CPU time, while holding the relative amounts of CPU time received by 
the other work classes constant, type: 

dwc 50 30 20 10 

The actual effect is to give the four work classes 46%, 27%, 18%, and 9%, respectively. 



Name: delete_jiiaiL-table_entry 

SYNTAX AS A COMMAND 

del ete_mai 1__table_entry name 

FUNCTION 

removes entries from the mail table that are not associated with a registered user. 

ARGUMENTS 

name 

is a string that specifies a mail table entry that is to be deleted. Enclose it in 
quotation marks if it contains blank spaces. 
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NOTES 

In order to maintain consistency with the person name table (PNT), this command will 
not permit entries which are associated with registered users to be deleted. If the mail 
table entry has aliases then the alias entries are also deleted. 

ACCESS REQUIRED 

The user must have e access to the gate mail_table_priv_. 



Name: delete old pdds 

SYNTAX AS A COMMAND 

del ete__o1 d_pdds {-control__args} 

FUNCTION 

deletes old copies of >process_dir_dir and system_library_l created during bootload. 
This command is intended mainly for use in the Utility. SysDaemon's start_up.ec. If j 
the system is unable to boot for lack of quota, boot to standard and run from the j 
initializer process in admin mode. | 

CONTROL ARGUMENTS 

-exclude_first N 

specifies that the first N old copies of >process_d i r_d i r and >system_l ibrary_l 
(that is, the N oldest ones) are not to be deleted. 

-excludejast N 

specifies that the last N old copies of >process_d i r_d i r and >system_l ibrary^l 
(that is, the N most recent ones) are not to be deleted. 

ACCESS REQUIRED 

This command requires access to the hphcs_ gate. 
NOTES 

The old copies of >process_di r_di r are named pdd. [unique], and branch directly 
off the root. The old copies of >system_li brary_l are named s 1 1 . [un i que] , and 
also branch directly off the root. 

The control arguments for specifying that some old >process_d i r_d i r copies are not 
to be deleted are useful when it is necessary to have the process directory contents of 
processes at the time of a crash, in order to debug system problems. 
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If the process running delete_old_pdds has access to the soos privilege, it will be 
enabled to allow salvaging of soos directories. It is recommended that the 
* delete_old_pdds command be run in a process with access to the soos privilege. 



Name: delete proj 

SYNTAX AS A COMMAND 
de]ete_proj Project_id 
FUNCTION 

is used by the dproj command in the master.ec segment. It does a portion of the 
work of deleting a project. (Other commands called by master.ec do the remainder.) 

ARGUMENTS 

Projected 

is the name of the project to be deleted. 
NOTES 

The entries for the specified project are marked as deleted in the administrator's copy 
of the SAT (smf.cur.sat) and in the projfile and reqfile segments. Those entries are 
not physically removed however. In addition, the name "delete. Project_id.pdt" is added 
to the Projected. pdt segment in >scl>pdt as a reminder that this PDT should be 
deleted (by the system administrator) after the next monthly bills are run. 



Name: delete registry 

SYNTAX AS A COMMAND 
de I ete_reg i stry paths 
FUNCTION 

deletes old unused RCP Resource Management registries. These registries must have 
been previously removed from service via the remove_registry command. 

ARGUMENTS 

path 

is the pathname of an old registry to be deleted. The star convention is accepted. 
If the suffix old is not given, it is assumed. 
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ACCESS REQUIRED 

You need access to the rcp_admm_ gate. 



Name: delete voliime_registratioii, dvr 

SYNTAX AS A COMMAND 
dvr -contrcl^args 
FUNCT/ON 

deletes the registration information for a physical or logical volume. 
CONTROL ARGUMENTS 

You can supply only one of these two control arguments: 

-logicaUvolume LVJ^AME. -Iv LV.NAME 

specifies that the registration information for the given logical volume is to be 
deleted. 

-physical^volume PV^NAME, -pv PV_NAME 

specifies that the registration information for the given physical volume is to be 
deleted. 

NOTES 

You can't delete the last physical volume registered to a logical volume. You must 
delete the whole logical volume registration. 

When deleting a logical volume, all physical volumes in that logical volume are 
deleted. 

There is no reason to delete and reregister volumes. If there is an error in 
registration, use change_volume_registration to correct it 

ACCESS REQUIRED 

You need re acc^ to the mde.jiriv. page and em to >lv. 
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^sms! dcrsgistsr rssourcs. drr 
SYNTAX AS A COMMAND 
I drr type STRl . . .STRn 
FUNCT/ON 

makes a particular resource unknown to the system. The deregistration process informs 
the system that the resource is no longer available for use. 

ARGUMENTS 

type 

I is a resource type defined in the resource type description table '(RTDT). 
I STRs 

is the unique identifying name of the particular resource being deregistered. If 
you specify STR with a leading hyphen, precede it by -name (-nm). 

ACCBSS REQUIRED 

You require execute access to the rcp_admin_ gate. 
NOTES 

To be deregistered, the resource must be in the free state. A resource owned by a 
user (or belonging to the system pool) must be released (see the release.resource 
I command in the Commands manual, AG92) before you deregister it. 

If you give multiple resource names to drr and an error occurs in the der^istration 
of any of these resources, none of the resources are der^tered. 



Name: diskL.meters 
SYNTAX AS A COMMAND 

disk^meters {subsystem_name} {-contro1_args} 
FUNCTION 

prints statistics for each disk subsystem. A disk subsystem is a set of channels and 
devices where every chamiel can r^h every device. 
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ARGUMENTS 
subsystem_name 

is the name of a disk subsystem (dska, dskb, dskc, etc.) for which information is 
to be printed. If not specified, information for all subsystems is printed. 

CONTROL ARGUMENTS 

-channels, -chn 

requests subsystem channel information. 

-detail, -dtl 

requests detailed drive information. 

-long, -Ig 

requests all information obtained by the -channels, -detail, -queues, -system 
control arguments. 

-queues, -q 

requests drive queue information. 

-report_reset, -rr 

generates a full report and then resets the metering interval to begin at the 
current point in time. 

-reset, -rs 

resets the metering interval to being at the current point in time. No report is 
generated. A reset is accomplished by making a copy of the statistics as of the 
reset time. Future invocation of the command will display the difference between 
current statistics and the copy. 

-system, -sys 

requests system statistics and optimizing information, 
-unreset, -urs 

resets the metering interval to begin at system initialization time. 
ACCESS REQUIRED 

This command requires access to phcs_ or metering_gate_. 
NOTES 

The following are brief descriptions of each of the variables printed by disk_meters. 
call locks 

are lockings of a disk subsystem in order to queue read or write operations. 
Information displayed includes the number of lockings (Count), the number of 
waits for the lock (Waits), the percentage of lockings that needed to wait 
(%Waits), and the average wait time (Avg. Wait (ms.)). 
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run locks 

are lockings of a disk subsystem in order to check the status of all devices and 
channels. Run is called by page control on all subsystems when too many write 
transfers are pending. Information displayed is the same as for call locks. If the 
number of run lockings is greater than a tenth of the number of call lockings, a 
transfer bottleneck probably exists at the subsystem, channel, or device level. 

interrupt locks 

are lockings of a disk subsystem at interrupt time. Information displayed is the 
same as for call locks. 

allocations 

are metered whenever a transfer request is queued within a disk subsystem. 
Information displayed includes the number of allocations (Count), the number of 
times queueing of the request had to wait for the completion of a previous 
request, i.e., no free queue entry was available for use (Waits), the percentage of 
allocations which had to wait (%Waits), and the average time in milliseconds until 
a queue entry became available (Avg. Wait (ms.)). If the allocation %Waits is 
greater than 2%, a transfer bottleneck probably exists at the subsystem, channel, 
or device level. 

For each drive in the subsystem, the following meters are displayed. 
Reads 

is the number of page or volume table of contents (VTOC) reads from the 
device. 

Writes 

is the number of page or VTOC writes from the device. 
Seek Distance 

is the average seek distance in cylinders on the device. If this average is greater 
than a third of the number of cylinders, then the pages are probably poorly 
distributed on the pack. 

j connects 

I number of channel connections made. 
I int w/o term 

I number of interrupts without terminate status, 
run polls 

number of lO's seen by RUN polling. 
I get_io w/o term 

I number of io_manager calls not returning terminate. 
I term not active 

j number of interrupts with terminate on an inactive channel. 
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lOI 

the channel has been released to lOI use. 
INOP 

the channel is deemed to be inoperative. 
BROKEN 

the channel is deemed to be broken. 
EXAMPLES 

The following is an example of the information printed when the command is invoked 
with the -channels control argument specified. 

dska: Channel information. 

A8: 42530 connects, I63 int w/o term, 385 run polls 

A 12: 4559 connects, 13 int w/o term, 129 fun polls 

A9: 1307 connects, I5 int w/o term, 225 fun polls 

The following is an example of the information printed when the command is invoked 
with the -detail control argument specified. 
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TEST 0 UNLOADS, 39 TESTs 
Channels 1.05% busy, 212 Combs. 

The following is an example of the information printed when the command is invoked 
with the -queues control argument specified. 

dska_04 Queue: Ave I6.I, Alloc 99, Max Depth 5O/28O, Cur Depth 0 

This indicates the average queue depth for the specified number of queue allocations, 
the maximum depth since max_depth_meters were last reset and the current depth in 
the queue. Requests are only queued if a drive is busy and /or it already has requests 
queued. 



2-129 



GB64-00 



disk meters disk meters 



The following is an example of the information printed when the command is invoked 
with the -system control argument specified. 

FREE Queue: Ave 6.2, Alloc 60237, Max Depth 99/280, Cur Depth 1 
System Factors: stagnate time 5*000 seconds, 378 bail outs. 



Maximum Depth Meters reset at: 
PageRd Max Load 6, Depth 
PageWt Max Load 210, Depth 
VtocRd Max Load 6, Depth 
VtocWt Max Load 12, Depth 



06/07/8i+ 2207.7 mdt Thu 
0 (PageRd), Fraction 1.0000 
0 (PageWt), Fraction 1.0000 
0 (VtocRd), Fraction 1.0000 
0 (VtocWt), Fraction 1.0000 



This indicates FREE Queue use, stagnation time beyond which the system does disk 
combing and the number of times that the ALM driver had to call the PLl driver to 
process complex interrupt information. The time that max_depth meters were last reset 
at is given, as is the current status of the system-wide load optimization algorithm. 

The following is an example of the information printed when the command is invoked 
with no control arguments. 
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This indicates the metering period, the sub-system and lock information for the 
sub-system, and individual drive 10 information for all drives which have performed 
10 in the metering period. Typically 0 counts are suppressed to highlight useful 
information. 
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Name: disk queue, dq 

SYNTAX AS A COMMAND 
dq subsytem_name 
FUNCTION 

prints out the subsystem channel activity and the waiting I/O requests queued for a 
given secondary storage subsystem. 

ARGUMENTS 

subsytem_name 

is the subsystem name and can be of the form dska, dskb, dskc, etc. 
ACCESS REQUIRED 

This command requires access to phcs_ or metering_gate_. 
NOTES 

The disk_queue command accepts only one subsystem name at a time; therefore, 
multiple subsystem names should be enclosed in parentheses. For the subsystem 
specified, the number of connects on each of its channels is printed. For each waiting 
request, the following information is printed: 

P 

is the priority of the request (l=high: O=low). 

RW 

indicates the type of request (R=read; W=write). 

VP 

indicates the type of request (P=page; V=volume table of contents entry). 
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DV 

represents the device to which the request is directed. 
SECTOR 

is the sector to or from which input/output is done. 
MEM 

is the main memory address to or from which input/output is done. 



Name: disk stat print 

SYNTAX AS A COMMAND 

d i sk_stat_pr i nt {path} {-contro1_args} 

FUNCTION 

prints the disk_stat segment that is created by the sweep command. Optional control 
arguments cause the information to be presented in a variety of ways, to facilitate 
analysis of disk usage patterns. By default, a header is printed, followed by one line 
for each directory in the disk_stat segment, and a totals line. 

ARGUMENTS 

path 

is the pathname of the disk_stat file to be printed. If path is not given, the 
disk_siat segment in the working directory is assumed. 

CONTROL ARGUMENTS 

-level N, -lev N 

summarizes each subtree that begins at level N: prints no lines with level numbers 
greater than N (where N is an integer from 0 to 16). The effect of this 
argument is to make the output appear as if no directories with quotas existed 
below level N in the hierarchy since the directories below level N have their 
usage figures included in those of whatever level N directory they are inferior to. 



The default value for N is 16, causing all directories in disk_stat to be printed 
individually. The root's level is 0. A directory is said to be below level N if its 
level number is greater than N. A value of 2 for N causes the disk usage of 
each project to be displayed in a single line; a value of 3 causes the usage of 
each user to be displayed (provided that the user directories have quotas). 
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-logica]_volume, -Iv 

prints the name of the logical volume on which segments contained in each 
directory reside and prints the usage figures for each logical volume. An extra 
column is printed in the directory line, giving the logical volume index (Ivix). 
This is merely the line number in the table of logical volume totals that is 
printed after the regular totals lines. An Ivix of 0 indicates that the subtree 
summarized by the line contains segments that reside on more than one logical 
volume; an Ivix of -1 indicates a logical volume not known to the system. 

-subtotal, -stt 

prints subtotal lines giving the totals for each subtree. Each time a directory is 
encountered whose level number is less than that of the preceding directory, one 
or more subtotal lines are printed. This argument causes the maximum amount of 
subtotal information to be printed. Some users may find the resulting output too 
cluttered to be easily read. To produce less information, but in an easier to read 
format, see the -level control argument. 

-total, -tt 

does not print a line for each directory; rather prints a totals line (plus any other 
lines specified by other arguments). 

NOTES 

The first date printed in the header is the date of the last billing. It is filled in by 
charge_disk if the disk_stat file is the one used by the daily disk accounting job. 
This dale is 0 in files created separately (e.g., for use in disk usage analysis). 

Although the output of disk_stat_print is designed to be printed on a line printer 
(using the file_output and dprint commands, described in the Multics Commands and 
Active Functions manual, Order No. AG92), it can be printed on a terminal if the 
carriage is wide enough. Each line consists of approximately 10 characters followed by 
a pathname. Pathnames can be up to 168 characters long but are typically less than 50 
characters long. 

EXAMPLES 

d i sk_stat_pr i nt A 1 pha .d i sk_stat -level 3 

prints one disk usage line for each user on the Alpha project, assuming that the 
segment Alpha.disk_stat was created as shown in the example under the sweep 
command. 

d i sk_stat_pr i nt Al pha.di sk_stat -total 
prints a single line giving the disk usage for the entire Alpha project. 
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Name: disk usage stat 

SYNTAX AS A COMMAND 
d i sk_usage_stat path 
FUNCTION 

gathers statistics on a hierarchy subtree. It produces a report describing; (1) the 
number of segments, links, directories, and names by hierarchy depth, (2) the 
distribution of segments by date of last reference and last modification, (3) the 
distribution by segment size, (4) the distribution by number of names, (5) the 
directory distribution by number of names, and (6) the counts by starname (see the 
Multics Programmer's Reference Manual, Order No. AG91, for a discussion of 
starnames). 

ARGUMENTS 

path 

is the pathname that specifies the hierarchy inferior to path to be scanned. The 
default is ">". 

NOTES 

The report is typed on the user's terminal. 

The listing by starname is controlled by the contents of the segment starname_list in 
the user's working directory. This segment consists of starnames. one per line. If the 
starnamejist segment does not exist, a single starname, **. which matches all entries, 
is assumed. 



Name: disklow 

SYNTAX AS A COMMAND 
disklow {n_left {pet}} 
FUNCTION 

scans the projfile segment and reports on each project whose remaining disk storage 
(difference between quota and used) is low. The control arguments allow the system 
administrator to check the disk storage by either number of free records or percent 
of disk occupied or both. 
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ARGUMENTS 
njeft 

prints a line for all projects with less than n_left free records, where nJeft is an 
integer value. 

pet 

prints a line for all projects occupying more than the specified percent of their 
disk storage quota, (pet is a value in the range 01 through 99). 

NOTES 

A value for n_left must be given in order to give pet. The default values for n_left 
and pet are 20 and 90, respectively. If the system administrator wants to receive only 
percentage information, n_left must be specified as 0. 

The projfile segment is assumed to be in the working directory and is an implicit 
input to disklow. 



Name: display account status, das 

SYNTAX AS A COMMAND 

das {Project id} {"control args} 

FUNCTION 

prints the latest accounting information for a project. The information is stored in the 
PDT of that project and is correct as of the last time the daily accounting job was 
run; it is usually run every night. 

ARGUMENTS 

Projected 

is the Project_id of the project. If this argument is not given, the project under 
which the project administrator is currently logged in is assumed. 

CONTROL ARGUMENTS 

-brief, -bf 

prints a one-line summary of the account information, 
-^long, -Ig 

prints all information found in the projfile (project registration segment) entry 
and the reqfile (requisition segment) entry. 
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-no_header, ~nhe 

suppresses priming of the header. 

ACCESS REQUIRED 

The user must have read access to the PDT to use this command; usually only project 
administrators have such access. 

NOTES 

If neither the -brief nor -long control argument is given, all information about 
charges is printed. 

See also the proj_usage_report command to get a brief summary of each user's 
resource consumption and the print_pdt command to get more detailed information 
about each user. 

EXAMPLES 

The following example illustrates the output of the das command when it is used with 
the -long control argument: 

das Multics.pdt -long 



Multics.pdt 12/01+/84 0855.3 

Account information copied 12/03/84 213O.7 

Projectid: Multics; 

REQF I LE 

account: SYSPROG 

reqno: Multics 

rate structure: default 

qf 1 ag : 

date on: 03/13/75 Mb^-^ est Thu 
date off: 

billing name: System Administration 

billing addr: Accounting Office 

charge this month: $ 57285.7^ 

charge this req: $ 24^583. 92 

req amount: $ 0.00 balance: OPEN 

cutoff date: 01/01/99 125i+.i+ est Fri 

PROJF ILE 

title: Worker Bees 

investigator: John Gintell 

i nv address: Right Here 

supervisor: CTC 
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sup addr: 

sup phone: 

date on: 

date off: 

disk page-months: 

disk quota: 

disk use: 

d i r disk use : 

misc charges: 

# m i sc charges : 

SAT 
attr i butes : 



r I ng: 
a 1 i as : 

default group: 
authorized groups: 
max grace: 
audit flags: 

author i zat i on: 
days to cutoff: 
percent balance: 
dol 1 ars to cutoff : 



There 
phone_no 

03/13/75 125^.5 est Thu 

29296, $ 87.89 
67538 

27329 
2214 
$ 0.00 
0 



pr i mary__l i ne, guaranteed_logi n, anonymous, nopreempt, 
dialok, multip, bumping, brief, vinitproc, vhomedir, 
nostartup, daemon, igroup, save_pdir, d i sconnect_ok ; 

1.5 
m 

SysProg 
Admi n 
2880 

seg_i nit, dir_init, 
acv_mode, acv_ring, 
system_low : system_high 
5143 
100% 
$ 0.00 



mc_seg_init, no_access 
no_wakeup, sys_priv 



i pr fault, 



The following example illustrates the output of the das command without the -long 
argument: 



das Multics.pdt 



Proj ect i d : 
charge th i s month 
charge this req: 
req amount: 
cutoff date: 
disk page-months: 
disk quota: 
disk use: 
dir disk use: 
misc charges: 
# m i sc charges : 



Mu 1 1 i cs . pdt 

Account information copied 

Mu 1 1 i c s ; 

$ 57285.74 

$ 2414583.92 



$ 

01/01/99 
29296, $ 
67538 

27329 
2214 
$ 0.00 
0 



0.00 

1254.4 

87.89 



bal ance: 
est Fri 



12/04/84 0857.7 
12/03/84 2130.7 

OPEN 
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Name: display anst 

SYNTAX AS A COMMAND 

d i spl ay__anst {channel_name} {-contro1_args} 
FUNCTION 

displays the Answer Table, which contains information about interactive users. The 
Answer Table resides in >scl>answer_table. 

ARGUMENTS 

channel_name 

names a channel whose Answer Table entry is to be displayed. 
CONTROL ARGUMENTS 
-active 

displays entries in Answer Table for active communications channels (channels that 
have been hung up, are listening for a user to dial up, are connected to a user 
(dialed), have logged in a user, or are attached to a running a process). This is 
the default. 

-all, -a 

displays all table entries. 

-channel channel_name, -chn channel_name 

names a channel whose Answer Table entry is to be displayed. The channel_name 
argument has the format described above. 

-dial 

displays entries in Answer Table for dialed communications channels (channels that 
are connected to a user (dialed), have logged in a user, or are attached to a 
running process). 

-in 

displays entries in Answer Table for logged in users, 
-lock 

displays entries in Answer Table which are locked. 

-name Person_id, -nm Person_id 

displays entry or entries associated with the given Person_id. 

-no_header, -nhe 

suppresses display of the heading information contained at the beginning of the 
Answer Table. 
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-octal, -oc 

displays header and entries in an octal dump, as well as in interpretive format. 

-pathname path, -pn path 

gives the pathname of the table to be displayed. If omitted, the system Answer 
Table in >scl>answer_table is used. 

NOTES 

The -all, -active, -dial, -in, -lock, -name and -channel control arguments and the 
channel_name argument select entries to be displayed. If more than one is given, an 
entry is displayed if it matches any of the conditions specified by the arguments. If 
none are given, the entries for all active communications channels are displayed. 

EXAMPLES 

To display the entire Answer Table, type: 
d i spl ay_anst 

To display only the Answer Table entry for user Apple on any project, type: 
display_anst -nhe -name Apple 

To display the Answer Table entry for the user on channel "a.l008", type: 
display_anst -nhe a.l008 



Name: display aste 

SYNTAX AS A COMMAND 

display_aste {pathname} {-control_args} 

FUNCTION 

displays the Active Segment Table Entry (ASTE) and, optionally, the file map of an 
active segment. 

ARGUMENTS 

pathname 

is the pathname of the desired segment. If a pathname is not specified, the 
-hardcore control argument must be used. 
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I CONTROL ARGUMENTS 

I -hardcore NAME, -he NAME 

I display the ASTE and, optionally, the file map of the hardcore segment 
I indentified by NAME, where NAME is the octal segment number or SLT name 
j of the desired segment. 

I -offset OFFSET, -at OFFSET 

j specifies that the ASTE at sst_seg/OFFSET will be displayed. 

I -file_,map, -fm 

I specifies that the file map will be displayed. 

I -no_file_map, -nfm 

I specifies that no file map will be displayed. This is the default. 

I -no_octal, -noc 

I specifies that the ASTE is not to be displayed in octal format. This is the 
I default. 

I -octal, -oc 

I specifies that the ASTE is to be displayed in octal format, 
j ACCESS REQUIRED 

I This command requires access to ring_zero_peek_, phcs_, and mdc_. 

I EXAMPLES 

I d i spl ay_aste > 

I ASTE for > at 7^530 in sst_seg 

fp: 7664, bp: 15076^4, infl: 0, infp: 7520 

strp: 30300, par_astep: 0, UID: 777777777777 

I msl: 205, csl: 6, records: 6, np: 5 

DTU: 198i+-01-23 08:4i4: I8 

DTM: 198i+-01-23 09:02:09 

I ON: usedf gtms nqsw dirsw master_dir tqsw(S) tqsw(D) dnzp fms 

I OFF: init gtus he hc_sdw any_access_on wr i te_access_on 

I i nh i b i t_cache exp 1 i cl t_deact_ok deact_error hc_part fm_damaged 

I dius nid ehs volmap__seg npfs ddnp synchronized fmchanged 

I fmchanged 1 damaged pack_ovfl 

quota: (137171, 1^7361), used: (11141, 1019) 

pvtx: 7. vtocx: 0 

pvname: rpv disk name: dska_07 



display_aste > -fi1e_map 
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ASTE for > at 7653O in sst_seg 

fp: 76644, bp: 150764, infl: 0, infp: 7520 
strp: 30300, par^astep: 0, UID: 777777777777 
msT: 205, csl: 6, records: 6, np: 5 
DTU: 1984-01-23 08:44:18 
DTM: 1984-01-23 09:02:49 

ON: usedf gtms nqsw dirsw master_dir tqsw(S) tqsw(D) dnzp fms 

OFF: init gtus he hc_sdw any_access_on wr i te_access_on 

i nh i b i t_cache expl i c i t_deact_ok deact_error hc_part fm_damaged 
dius nid ehs volmap_seg npfs ddnp synchronized fmchanged 
fmchangedl damaged pack_ovfl 

quota: (137171, 147361), used: (11141, IOI9) 

pvtx: 7, votcx: 0 
pvname: rpv disk name: dska_07 

File mape: 0 Memory address I67040OO '^er,phu,phul j'^pmh.^phml ,'^wi red,^os,\|al id 
Disk address: Disk page 14504 

1 Memory address 12342000 ^er , phu , phu 1 , ^pmh , '^phml , ^wi red , '^os , va 1 i d 

Disk address: Disk page 14506 

2 Memory address 12336000 ^er ,phu,phul ,'^pmh,^phml ,^wi red.'^osjval id 

Disk address: Disk page 14510 

3 Memory address 12340000 '^er,phu,phul j'^pmh.^phml ,^wi red,'^os,val id 

Disk address: Disk page 14512 

4 Memory address 12344000 ^er , phu , phu 1 , ^pmh , ^phml , ^wi red , "^os , va 1 i d 

Disk address: Disk page 14514 

5 Disk page 42021 

6 Null address from f i 1 l_page_tab 1 e 



Name: display aut 

SYNTAX AS A COMMAND 
disp1ay_aut {absN} {-control_args} 

FUNCTION 

displays the Absentee User Table (AUT), which contains information about absentee 
users. The Absentee User Table resides in >scl>absentee_user_table. 

ARGUMENTS 

absN 

names the absentee process whose Absentee User Table entry is to be displayed 
(e.g., absl, abs2). 
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CONTROL ARGUMENTS 
-active 

displays entries in Absentee User Table for absentee processes that are currently 
running a job (this is the default). 

-all, -a 

displays all table entries. 

-lock 

displays entries in Absentee User Table which are locked. 

-name Person_id, -nm Person_id 

displays entry or entries associated with the given Person_id. 

-no_header, -nhe 

suppresses display of the heading information contained at the beginning of the 
Absentee User Table. 

-octal -oc 

displays header and entries in an octal dump, as well as in interpretive format. 

-pathname path, -pn path 

gives the pathname of the table to be displayed. If omitted, the system Absentee 
User Table in >scl>absentee_user_table is used. 

NOTES 

The -all, -active, -lock and -name control arguments and the absN argument select 
entries to be displayed. If more than one is given, an entry is displayed if it matches 
any of the conditions specified by the arguments. If none are given, the entries for 
absentee processes which are currently running a job are displayed. 

EXAMPLES 

To display the entire Absentee User Table, type: 
d i spl ay_aut 

To display only the Absentee User Table entry for user Apple on any project, type: 

display_aut -nhe -name Apple 
To display the first absentee process, type: 

display_aut absl 
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Name: display branch 

SYNTAX AS A COMMAND 

d i spl ay_branch {-control_arg} target 

FUNCTION 

prints out information about directory entries that is not returned by the status 
command and lists the segment UID and the location of the branch. It does not 
access the VTOCE of the segment for any information. 

ARGUMENTS 

target 

indicates the segment whose branch is to be displayed. Any of the following 
forms can be used to specify the target segment: the pathname of the segment, 
the octal segment number of the segment, or the octal pointer representation of 
the branch address to be displayed (e.g., 260 1 1664). 

CONTROL ARGUMENTS 

-name, -nm 

must be specified before any pathname that is, or that can be construed as. a 
valid octal number. 

ACCESS REQUIRED 

This command requires access to the phcs_ gate. 



Name: display cache threshold 

SYNTAX AS A COMMAND 

d i spl ay_cache_threshol d {-control_args} 

FUNCTION 

displays the current cache error threshold values. 

CONTROL ARGUMENTS 

-system 

displays the threshold values in the per-system data base. 
-per_process 

displays the per-process threshold values. This is the default 
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Name: display cdt 

SYNTAX AS A COMMAND 

display_cdt {channel} {-control_args} 

FUNCTION 

enables a qualified user to display the contents of a channel definition table (CDT). 

ARGUMENTS 

channel 

is the name of the communications channel for which the CDT entry is to be 
displayed. The star convention is allowed. 

CONTROL ARGUMENTS 

-all, -a 

displays names and CDT indices for all channels in the CDT. 
-brief, -bf 

displays only channel names and CDT indices (without channel or FNP details). 
This is the default for the -all and -subtree control arguments. 

-cmf path 

creates a CMF in the segment named path in a form suitable to cv_cmf, based 
on the contents of the CDT. 

-header, -he 

displays the CDT header variables in addition to other requested information, 
-long, -Ig 

displays detailed information for the specified channel or FNP. This is the default 
unless -all or -subtree is specified, in which case -brief is the default. 

-no_header, -nhe 

suppresses display of the CDT header variables. This is the default. 

-pathname path, -pn path 

displays the CDT whose pathname is path. By default, the CDT in the segment 
>scl>cdt is displayed. 

-subtree 

displays the names and CDT indices for all subchannels (if any) of the specified 
channel. 
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NOTES 

If display _cdt is specified with no channel name and no control arguments, a usage 
error notification is returned. Specifying channel name only, with no control 
arguments, results in a -long display. 

The display_cdt command enables the user to check for inconsistencies in a CDT 
before unnecessarily undertaking corrective action. 

The user must have r access to the CDT to invoke the display_cdt command. 
EXAMPLES 

To display the entire system CDT, specify: 
display_cdt -all -header 

To display the system CDT entry for channel a.hOOO only, specify: 

display_cdt a.hOOO 
To display all the subchannels of multiplexer a.h026.1, specify: 

disp1ay_cdt a.h026.1 -subtree -long 



Name: display cpu error 

SYNTAX AS A COMMAND 

d 1 sp] ay_cpu_er ror {-control_args} 

FUNCTION 

scans the syserr log and displays machine conditions and history registers. 

CONTROL ARGUMENTS 

-from DT, -fm DT 

starts scanning the log at the date/ time given. 

-to DT 

stops scanning the log at the date/ time given, 
-for T 

computes the ending time from the starting time, where T is a relative time (such 
as "Ihour"). 
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-cpu CPU.LIST 

displays information for the CPUs specified, where CPU_LIST is a list of CPU 
tags (e.g., "a c"). 

-nothread 

specifies that the history registers are not to be threaded. The history registers 
will be output in octal with no interpretation. The default is off. 

-expand, -exp 

specifies that the history registers are not to be threaded but that they are to be 
interpreted. 

I -match STR...STRn 

I matches strings against messages in the log. where STR is a text string. Messages 

I are defined to contain process or machine condition information. Any message 

I that contains a STRi is displayed. 

I -exclude STRl...STRn, -ex STRl...STRn 

I matches strings against messages in the log as -match, where STR is a text string. 
I Any message that contains a STRi is NOT displayed. 

I -all 

I specifies that ail log entries that are defined to contain processor machine 
j information can be displayed. 

I ACCESS REQUIRED 

I Read permission is required on the log segments themselves and status permission is 
j required on their containing directories. 

NOTES 

If -from DT is not given, the scan starts with the earliest entry in the syserr log. 
The ending time can be specified by using -for or -to, but not both. If both are 
omitted, the scan terminates with the last entry in the log. All dates and times must 
be in a format acceptable to the convert_date_to_binary_ subroutine described in the 
Multics Subroutines and 1 10 Modules manual, Order No. AG93. 

I Unless the control arguments -all, -match, or -exclude are specified, only hardware_fault 
I entries will be processed. 
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Name: display^disk^label, ddl 
SYNTAX AS A COMMAND 
ddl DEVICE {-control _args} 
ddl {PVNAME} {-control_args} 
FUNCTION 

displays infonnation recorded in the physical volume label for a storage system disk 
volume and optionally displays information recorded in the physical volume table entry • 
(PVTE) for the associated disk unit 

ARGUMENTS 
DEVICE 

specifies the disk subsystem and unit on which the volume is mounted (e.g., 
dska_05 or dskk_00a). 

PVNAME 

is the physical volume name (e.g., rpv). 
CONTROL ARGUMENTS 
-long, -Ig 

displays information recorded in the PVTE. 
-pvid PVID 

specifies the disk unit by the unique identifier assigned to the physical volume 
when it was registered (PVID). a 12-digit octal number. 

ACCESS REQUIRED 

You need access to phcs.. 

NOTES 

Specify a disk unit by only one of the following: DEVICE, PVNAME. or "-pvid 
PVID*". The requested unit must represent a mounted storage ^tem volume. 
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EXAMPLES 



ddl fpdi rOl -long 
Label for Multics Storage System Volume fpdirOI on dskk_00a 3380 



PVID 
Ser i a1 

Logical Volume 
LViD 

Subvolume a 1 of 2 

Regi stered 

D i smounted 

Nap Updated 

Salvaged 

Boot load 

Reloaded 

Dumped 

I ncremental 
Consol i dated 
Complete 

I neons i stencies 

Minimum A!M 
Maximum AIM 



5353^1556672 
fpdirOl 
fpdir 1 
5353^*1556533 



05/24/86 
11/07/86 
11/08/86 



11/08/86 



2031 


.3 


mst 


Sat 


2105 


.9 


mst 


Fri 


0558 


.6 


mst 


Sat 


0556 


.6 


mst 


Sat 



0:000000 
7:777777 



PVTE for Multics Storage System Volume fpdirOl on dskic 00a 3380 
at pvt|5374 



PVID 
LVID 

VTOCEs 
Number 
Left 

Records 
Number 
Left 

Subvolume Info 
sv_num 
num_of__svs 
record_f actor 
records_per__cyl 



5353'»1556672 
5353^*1556533 



10204 
10131 



51024 
49434 



0 
2 
0 
127 



neons i stencies 
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Volume Nap 



vol map seg ASTE 


102 


1120 


record 


stock 


104 


1440 


Page 0 


- Base 




1766 




Free 


70712 


Page 1 


- Base 


105766 




Free 


47520 


Page 2 


- Base 


205766 




Free 




0 


vtoce s 


stock 


104 1 1703 



ON: used is_sv s tor age_sy stem 

OFF: root_1v rpv permanent testing being_mounted bei ng_demounted 

removab1e_pack checker ead_ i ncomplete device^ Inoperative 
scav_ciieck_address deposi t_to_vo1map bei ng_demounted2 
pc_vacating vacating hc_part_used volmap_1ock_notify 
volmap_ldle_notify vtoc_map_1ock_noti fy dmpr_in_use (incr) 
dmpr_ i n_use (cons) dmpr_ i n_use (comp) 

Volume Map from PVTE 



First Record Size 

Oo lOo Label Region 

lOo 117560 VTOC Region 

117660 14352O0 Paging Region 

1555060 155704O Partitions 

1555060 Total Size 



Name: display.dut 

SYNTAX AS A COMMAND 

display^dut {source^name} {-control^args} 

FUNCT/ON 

displays the daemon user table (DUT)» which contains information about daemon users. 
The system DUT resides in >scl>daemon^user.table. 

ARGUMENTS 

source_name 

is the message coordinator source name associated with the daemon process whose 
DUT entry is to be displayed (e.g., cord, prta, vine, and vcomp). 
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CONTROL ARGUMENTS 
-active 

displays entries in the DUT for all daemon processes that currently exisL 
(Default) 

-all. -a 

displays all table entries. 

-lock 

displays entries in the DUT that are locked. 

-name Person_id, -nm Person_id 

displays the entry or entries associated with the given Person^id. 

-no__header, -nhe 

suppresses display of the heading information contained at the beginning of the 
DUT. 

-octal, -oc 

displays the header and entries in an octal dump, as well as in interpretive 
format 

-pathname path, -pn path 

gives the pathname of the table to be displayed. If omitted, the system DUT is 
used. 

NOTES 

The -a, -active, -lock, and -nm control arguments and source_name select entries to 
be displayed. If you give more than one. an entry is displayed if it matches any of 
the conditions specified by the arguments. If you give none, entries for active daemon 
processes are displayed. 

EXAMPLES 

To display the entire DUT. type: 
disp1ay_dut -al 1 

To display DUT entries for the daemon processes that currently exist, type: 
disp1ay_dut 

To display only the DUT entry for user 10 on any project, type: 
display_dut -nhe -name 10 
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To display the DUT entry for the process using the message coordinator source name 
vine, type: 

display^dut vine -nhe 



Name: display.fnp_Jdle 

SYNTAX AS A COMMAND 

di sp]ay_f np_idle {fnp_names} {-control -args} 
FUNCTION 

displays information on the Front-End Network Processor (FNP) idle time stored by 
the meter_fnp.idle command. The display can be either a summary or a line graph 
(histogram). 

ARGUMENTS 

fnp_names 

^ &e names of ^ FNPs for stias^ idle ^!ie mfonnatiiMi is to be displayed. 
If you supply no fnp_names, the display covers all FNPs for which information 
has been stored. 

CONTROL ARGUMENTS 

-directory path, -dr path 

specifies that information is to be taken from segments in the directory with 
pathname path (see meter.fnpjdle). (Default to display information from idle 
time segments in the working directory) 
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-from DT, -fm DT 

specifies that the display is to cover a period beginning no earlier than the 
date/ time value (DT). (A description of valid DT values is provided in the 
Mufti cs Programmer's Reference Manual, Order No. AG91.) TTie default is to 
start the display from the most recent idle time segment. 

-histogram, -hist 

causes output in the form of a histogram, where a line shows the busy percentage 
for each FNP at a given time interval. The -histogram and -summary control 
arguments are mutually exclusive, but one or the other must be specified. 

-interval N 

specifies that each line in the histogram represents an N minute interval. This 
control argument is ignored if -summary is specified. The default is 15 minute 
intervals. 

-linejength N, -11 N 

specifies the line length of the histogram as N columns (N cannot be less than 
38). This control argument is ignored if -summary is specified. The default is the 
user's terminal line length (or 80 if output is directed to a file). 

-summary, -sum 

requests a summary display of FNP idle information for the specified time period. 
The -summary and -histogram control arguments are mutually exclusive, but one 
or the other must be specified. 

-to DT 

specifies that the display is to cover a period ending no later than the date/ time 
value (DT). (A description of valid DT values is provided in the Multics 
Programmer's Reference Manual, Order No. AG91.) The default is to end the 
display with the latest available information. 

EXAMPLES 

The following com.m.and and resultant display represent a sample display_fnp_idle 
summary request in which FNP "a" was found to be 90.3% idle for the specified 
period (i.e., starting from the beginning of the most recent idle time segment and 
including the latest available information). Note that the busiest interval within the 
period is identified. 

d i spl ay_f np_i d 1 e a -summary 

FNP A idle from 01/04/84 0600. to 01/06/84 1436'.: 90.3% 

Busiest sample interval: 

01/05/84 1423. to 1424.: 43.7% idle 
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The following command and resultant display represent a sample display _fnp_idle 
histogram request for all FNPs for which idle time has been recorded. The time 
period starts no earlier than noon on 01/06/84 and includes the latest available 
information. The busy percentage for each FNP is given at 10-minute intervals. 

di splay_f np_idle -from "01/06/8^ 1200." -hist -interval 10 

%busy 0 10 20 30 ^tO 50 60 

I I I I I I I 

01/06/84 1330. A B C 

13^0. AC B 

1350. A CB 

11+00. A B 

UIO. A C 

li420. A B C 

11+30. A B C 



Name: display ioi data 

SYNTAX AS A COMMAND 

d i spl ay_i oi_data {-control_args} 

FUNCTION 

displays the ringO data base ioi_data. It can be used on a running system, an fdump, 
or a copy of ioi_data made with the copy_out command. 

CONTROL ARGUMENTS 

-all -a 

causes all the channel table entries (cte's) and device table entries (dte's) associated 
with the gTOUp{s) selected to be displayed. This control argument can be used in 
conjunction with -group or -gte. 

-force, -fc 

forces the display of certain control blocks and/or fields that the command might 
not otherwise display. For example, "-gte" displays only allocated group table 
entries (gte's); "-gte -force" displays all gte's, allocated or not. 

-header, -he 

causes the ioi_data header to be displayed. This is the default if no control 
blocks are selected. 
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-no_header, -nhe 

suppresses the display of the ioi_header. This is the default when a control block 
is selected. 

CONTROL ARGUMENTS FOR SELECTING 

The following control arguments are used to select where ioi_data is to be found. 
Only one control argument can be selected from this list. If none are specified, 
ioi_data is copied from ring_0 of the running system. 

-erf erf no 

specifies the number of the fdump to be analyzed. 

-segment path, -sm path 

specifies the pathname of the segment containing ioi_data. Normally, this segment 

is obtained from the running system using the copy_out command or from an 
fdump using the extract command. 

CONTROL ARGUMENTS FOR DISPLAYING 

The following control arguments specify which control blocks in ioi_daia are to be 
displayed. Only one control argument can be selected from the following list. If none 
of these control arguments are specified, all control blocks are displayed. 

-channel {channel_name} , -chn {channel_name} 

displays the channel table entry (cte) for the channel spe-cified. If channel name 
is omitted, all cte's are displayed. The channel name argument is in the form 
{tag} number, where tag is an lOM tag (a through h) and number is an octafl 
channel number. If tag is omitted, lOM a is assumed. 

-cte {octaLoffset} 

displays the cte at iom_data|octal_offset. If offset is omitted, all cte's are 
displayed. 

-device {device_name} , -dv {device_name} 

displays the device table entry (dte) for the device specified. If device_name is 
omitted, all dte's are displayed. 

-dte {octaLoffset} 

displays the dte at iom_data|octal_offset. If offset is omitted, all dte's are 
displayed. 

-group {device_name} , -gp {device_name} 

displays the group table entry (gte) for the device specified. If device_name is 
omitted, all gte's are displayed. The device_name can be either the full name of 
a nonmultiplexed device, such as prta, or the full name or first four characters in 
the name of a multiplexed device, such as tape or tape_02. 
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-gte {octal_offset} 

displays the gte at iom_data|octal_offset. If offset is omitted, all gte's are 
displayed. 

-user {Person_id.Project_id} 

displays the dte's of all devices assigned to the specified user. If Person_id.Project_id 
is omitted, the user's Person_id is assumed. Either Person_id or Projected can be 
omitted or an asterisk (*) can be used in their place. This argument is not 
allowed for -erf and will not work with -segment if the segment was created 
during a previous Multics bootload or if the users have since logged out. 

ACCESS REQUIRED 

To use this command on a running system, access to the phcs_ gate is required. 
NOTES 

The default action of this commmand, when invoked with no arguments, is: 
! d i sp 1 ay_i o i_data -group -all -header. 



Name: display kst entry 

SYNTAX AS A COMMAND 

d i spl ay_kst_entry {-control_arg} target 

FUNCTION 

prints the contents of a KST (known segment table) entry. The KST entry to be 
dumped can be indicated by either a segment number or a relative pathname of the 
associated object. 

ARGUMENTS 

target 

is either a segment number or a relative pathname. 
CONTROL ARGUMENTS 
-name, -nm 

must appear if target is a relative pathname that looks like a segment number. 
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EXAMPLES 



! display_kst_entry start__up.ec 



segno: 

usage: 

entryp: 

uid: 

dtbm: 

mode: 

ex mode: 

I nf count: 

hdr: 

flags: 



256 at 1551^70 

0, 0, 0, 0, 2, 0, 0, 0 

24315^52 
033100743603 
41633^652254 
7 (4, 4. 4) 

000000000000 (0, 0, 0) 

0 . 

4 



wr i te 



Name: display_log_segment 
SYNTAX AS A COMMAND 

di splay__]og__segment 1og_segment_ptr {-control^args} 
FUNCTION 

displays the internal infonnation of a log segment 

jk § mm WL §^f% 

MnfjuMc/vi o 
log^segment_ptr 

is a virtual pointer to the log segment to be displayed. It must be in a format 
acceptable to cv.ptr_ (this includes log segment entrynames and pathnames). You 
can supply only a log pointer. 

CONTROL ARGUMENTS 

-brief, -bf 

selects a short form for output 

-header, -he 

displays the log header. (Default) 

-long. -Ig 

selects a long form for output (Default) 

-no_header, -nhe 

does not display the log header. 
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""DO_print, — nj/i 

does not displays the status and contents of message entries. (Default) 
-no_trace 

does not display the status of messages. (Default) 
-print, -pr 

displays the status and contents of message entries. The information displayed is a 
superset of that displayed by -trace. 

-trace 

displays the status of message entries. 
NOTES 

This command is meant for analysis. Log perusal should be performed with 
monitor_sys_log, print_sys_log, or summarize_sys_log. 

If you use -nhe, -npr, and -no_trace together, you get an error message and no 
display. 



Name: display_mstb 
SYNTAX AS A COMMAND 
di sp1ay__mstb path 

FUNCTION 

displays information about the status of a multisegment table (MSTB). 

ARGUMENTS 

path 

is the pathname of the multisegment table. The PNT and URF are multisegment 
tables. 
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EXAMPLES 
The command 

! display_mstb >scl>PNT 
displays 

MSTB >scl>PNT is of type PNT. 

9 components, IO718 entries, SS'^S used, 28 deleted, 

6747 free. (37% full) 
entry size " kS% header size » I6, component size * 65536* 



Name: display__process_audit ^flags 

SYNTAX AS A COMMAND 

di splay_process_audi t_f lags {-control_args} 

FUNCTION 

displays the current state of the process security audit control flags. 
CONTROL ARGUMENTS 
-brief, -bf 

specifies that the short format is to be displayed. (Default) 
-long, -Ig 

specifies that the long format is to be displayed. 
ACCESS REQUIRED 

You must have re access to access.audit_gate_. 

NOTES 

For a description of the process audit flags, see the new_user command in this section 
and the section "Security Auditing" in the System Ad mm/ strati on Procedures (AK50). 

See also the set_process_audit_flags and edit_proces5_audit_flags commands. 

EXAMPLES 

! di splay__process_audi t_f lags 
f sob j =N/N, f sat tr«MA/MA,r cp«R/R,admin=R/R, spec ial«R/R, . . . 
. . .other"MA/R,admin_op,priv_op,faul t,smal l_,cc,moderate_cc 



11/86 



2-154.1 



GB64-O0A 



display_process_audit_flags 



display_psp 



! di splay_process_audi t_f lags -long 
Object Grant Level 



Deny Level 



F i le_System_Object 
Fi le_System_Attr ibute 
RCP_Object 

Adm i n I s trat i ve__Obj ect 
Speci al_Object 
Other_Obj ect 



No^Audit No_Audit 
Modi f y_Access Modify_Access 



Read Read 

Read Read 

Read Read 

Mod i f y_Access Read 



Audited Events: 



Admi ni strati ve_Operat ion 

Privileged Operation 

ACV/IPR_Fault 

Smal l_Covert_Channel 

Moderate Covert Channel 



Name: display ^psp 

SYNTAX AS A COMMAND 
display_psp {-control_args} 
FUNCT/ON 

displays selected information about distributed software found installed in online system 
libraries. The information includes marketing identifier. Software Technical Identifier 
(STI), copyright notice, and titles for the software requested. 

CONTROL ARGUMENTS 



returns selected information of all products found installed in the system libraries. 
(Default) 

-brief, -bf 

prints only the STI. (Default) 

-copyright 

returns the copyright notice for selected products if found installed in the system 
library. 

-long, -Ig 

prints the marketing identifier, STI, copyriglit notice, and titles selected. 
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display _pvte 



-match STR 

returns selected information for a specific product if it is installed in the system 
library, where STR is the marketing identifier. 

-name, -nm 

returns selected information about a named product. The name of the product 
will be the long name by which the product is most commonly referred, i.e., 
compose, cobol, or ted. 

NOTES 

The -brief and -long control arguments are mutually exclusive; the -match, -name, 
and -all control arguments are mutually exclusive. 



Name: display pvte 

SYNTAX AS A COMMAND 

d i spl ay_pvte {dskX_NN} {-contro ]_args} 

disp]ay_pvte {PVNAME} {-control_args} 

FUNCTION 

prints information recorded in the Physical Volume Table Entry (PVTE) for a storage 
system disk volume and optionally displays information recorded in the physical volume 
label. 

ARGUMENTS 
dskX_NN 

specifies the disk subsystem and unit on which the volume is mounted {e.g., 
dska_07). 

PVNAME 

is the physical volume name of the disk volume (e.g., rpv). 
CONTROL ARGUMENTS 
-long, -Ig 

causes information from the volume label to be printed also, 
-pvid PVID 

specifies the disk volume by the unique identifier assigned to the volume at the 
time it was registered (PVID). PVID is a 12-digit octal number, which can be 
obtained by using the list_volume_registration (Ivr) command. This control 
argument cannot be used if either dskX_NN or PVNAME is specified. 
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ACCESS REQUIRED 

This command requires access to metering_gate_. If the -long control argument is 
specified, then access to phcs_ is required. 

NOTES 

The disk volume specified must be a mounted storage system volume. 



Name: display rtdt 

SYNTAX AS A COMMAND 

d i sp] ay_rtdt {typel ... typeN} {-cont ro 1 _args} 
FUNCTION 

displays a resource type description table (RTDT). 

ARGUMENTS 

typei 

is the name of a resource type whose RTDT entry is to be displayed. If type is 
not given, all RTDT entries are printed. 

CONTROL ARGUMENTS 

-no_header. -nhe 

does not print the RTDT header comment. 

-pathname path, -pn path 

displays the contents of the RTDT specified by path. If this control argument is 
not specified, the RTDT residing in >system_control_l is displayed. 
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Name: display syserr log part 

SYNTAX AS A COMMAND 

di splay_syserr_log_part {args} {-control_args} 
FUNCTION 

displays portions of the syserr logging partition that exist on the disk, in order to 
diagnose and correct problems that might occur in the syserr logging partition. 

ARGUMENTS 

header, he 

prints the syserr log partition header. 

check D, ck D 

checks message threads in direction specified by D and validates message formats. 
Direction is specified by one of the following: 

forward, f forward checking only 
reverse, r reverse checking only 



message N, msg N 

displays a single message with message header information, message text and 
expanded binary output, and octal message words. The message to be displayed is 
specified by appending a positive or negative integer lo the message argument: 

N displays the log message that is N from the top 
-N displays the log message that is N from the last 



CONTROL ARGUMENTS 

-offset ADDR, -ofs ADDR 

displays message at word offset ADDR from the beginning of the syserr log. 

-number N, -nb N 

displays the syserr log message whose message number is N (decimal). 

ACCESS REQUIRED 

Read permission is required on the log segments themselves and status permission is 
required on their containing directories. 
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Name: display system audit flags 

SYNTAX AS A COMMAND 
d i spl ay_system_aud i t_f 1 ags 

FUNCTION 

displays the system parameters that control auditing of user access to system resources. 
NOTES 

See also the set_system_audit_flags command. 



Name: display vtoce 

SYNTAX AS A COMMAND 

display_vtoce PATHNAME j PVNAME VTOCX ~control_args 
FUNCT/ON 

displays the vtoce of a specified segment. 

ARGUMENTS 

PATHNAME 

is interpreted as the pathname of a segment or directory whose VTOCE should be 
displayed if you supply one noncontrol argument. 

PVNAME 

if you give two noncontrol arguments, the first is the physical volume name of 
the segment or directory whose VTOCE should be displayed. 

VTOCX 

if you specify two noncontrol arguments, the second is the octal vtoce index of 
the segment or directory whose VTOCE should be displayed. 

CONTROL ARGUMENTS 

"file map, ~fm 

displays the VTOCE file map. 

-header, -he 

displays the commonly used attributes of the segment stored in the VTOCE. 
(Default) 
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-long, -Ig 

displays the commonly used attributes ( as in -header) as well as additional 
attributes with less commonly used information. 

-no_file_map, -nfm 

does not display the VTOCE file map. 

-no_header, -nhe 

does not display the commonly interesting attributes of the segment stored in the 
VTOCE. 

-no_octal 

does not dump the entire VTOCE in octal, 
-octal 

dumps the entire VTOCE in octal. 
ACCESS REQUIRED 
You need access to phcs_. 
EXAMPLES 
d i spl ay_vtoce > 

vtoce ">" (Directory), vtove 0 on pvtx 7 (rpv) - 01/23/84 O908.9 est Men 

U!D = 777777777777, msl/csl/rec - 205 6 6 

Quota (S D) = (137171 U736I) 

Quota used (S D) = (lli+13 IOO6) 

Quota received (S D ) = (260543 0) 

Time-record product (S) 7-99551elij page-seconds 
updated at 01/21/814 1801.2 est Sat. 
Created 05/21/76 l8i+6.3 est Fri 
Dumped 01/23/814 0844.3 est Hon 

Used 01/21/84 1 801.2 est fion 

Modified 01/21/84 I8OI.I est Sat 

Switches: nqsw master_dir dnzp gtpd fm_checksum_val i d 
Access class: system_low 



di splay_vtoce > -long 

vtoce ">" (Directory), vtove 0 on pvtx 7 (rpv) - 01/23/84 0908.9 est Mon 
d i spl ay_vtoce > 

vtoce ">" (Directory) , vtove 0 on pvtx 7 (rpv) - 01/23/84 O908.9 est Mon 
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U!D = 111111111111 , msl/csl/rec = 205 6 6 

Quota {S D) = (137171 H736I) 

Quota used (S D) = (11413 IOO6) 

Quota received (S D ) = (2605^3 0) 

Time-record product (S) 7'99551el4 page-seconds 
updated at 01/21/8^+ l801.2 est Sat. 
Created 05/21/76 1846.3 est Fri 
Dumped 01/23/84 0844.3 est Mon 

Used 01/21/84 1801.2 est Mon 

Modified 01/21/84 I8OI.I est Sat 

Switches: nqsw master_dir dnzp gtpd f m_checksum_va 1 i d 

Access class: system_low 
UID path: > 

Parent vtocx -1 -of rpv of LV root 
Last incremental volume dumped on volume v-l4 
Last consolidated volume dumped on volume v-1231 
Last complete volume dumped on volume v-2 

d i spl ay_vtoce > -file_map -nhe 

vtoce ">" (directory), vtocs 0 on pvtx 7 (rpv) - 01/23/84 O9IO.3 est MMon 

File Map: 

0 Record 14504 

1 Record 14506 

2 Record 14510 

3 Record 14512 

4 Record 14514 

5 Record 42021 

6 Undocumented nul 1 address 777020 



64 Null address from update_vtoce 
255 Nul 1 address from update_vtoce 
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Name: dm lock meters 

SYNTAX AS A COMMAND 

dm_l ock_meters {-control_args} 

FUNCTION 

displays metering information about data management locking. The long version of the 
report provides information on locking for the entire system. The reset capability sets 
the meters to zero for the process only. 

CONTROL ARGUMENTS 

-brief, -bf 

selects the brief format for reporting on locking. (Default) 
-long. -Ig 

selects the long format for reporting on locking. 

-report_reset, -rr 

reports the current meters and then resets them. 

-reset, -rs 

resets the meters to zero without printing the report. 

ACCESS REQUIRED 

This command requires e (execute) access to dm_admin_gate_. 
EXAMPLES 

Two sample invocations of this command appear below. The first displays the brief 
format (default), the second, the long format. 

! dm lock meters 



Total metering 


t i me : 


3:09:51 




Ca 1 1 s to per system 


1 ock : 


208. 


Cal 1 s to unlock 


all : 




208. 


Locks by mode: 












S 


X 


FILES: 




0 


15^ 


CI 'S: 




0 


0 


Waits for locks 






0. 


Dead 1 ocks : 








Total Deadlock 


checks: 


0. 


Deadlocks detected: 




0. 



IS IX SIX 

3 51 0 
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! dm_1ock__nieters -1g 
Total metering time: 3:09:51 



Calls to per system lock; 
Cal Is to unlock all: 
Locks by mode: 

S 

NEW FILES: 0 
OLD FILES: 0 



208 
208, 



F I LES: 

NEW CI 'S: 
OLD CI 'S: 

CI 'S: 



Waits for locks: 
Dead 1 ocks : 

Total Deadlock checks: 
Two or more transactions: 
36 or less transactions: 
36 to 72 transactions: 
More than 72 transactions 
Deadlocks detected: 

Self youngest: 

Other youngest: 

Lock segments: 
B 1 ock a 1 1 ocates : 
Block frees: 



X 

15^ 
0 



0 
0 



IS 


IX 


SIX 


3 


51 


0 


0 


0 


0 


3 


51 


0 



0. 

0. 
0. 
0. 
0. 
0. 
0. 
0. 
0. 

1 . (max size 4096.) 

416. 

416. 
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Name: dm lock status 

SYNTAX AS A COMMAND 

d[n_l ock_status {-control__args} 

FUNCTION 

displays the status of all locks currently held or awaited by the current transaction or 
all transactions running under the current invocation of DMS. 

CONTROL ARGUMENTS 

-all_transactions, -atxn 

displays lock data for all transactions. 

-control_interval_locks, -cilk 

displays control-interval-level locks. This is the default 

-current_transaction, -ctxn 

displays lock data for the transaction currently owned by the process. This is the 
default 

-file_locks, -flk 

displays file-level locks. This is the default 

-header, -he 

displays data from the header of the lock database. 

-no_control_interval_locks, -ncilk 

suppresses the display of control-interval-level locks. 

-no_file_locks, -nflk 

suppresses the display of file-level locks. 

-no_header, -nhe 

suppresses the display of data from the header of the lock database. This is the 
default 

ACCESS REQUIRED 

This command requires e (execute) access to dm_admin_gate_. 
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EXAMPLES 
! dm lock status 



Pierret.Mul tics OIO5OO236OI5 Transaction 5 
Lock UID=135165^13304 Z\=k 

Owner P i erret .Mul t i cs OIO5OO236OI5 Txn 5 Mode X 
Lock UID=1351^5^13304 Cl=3 

Owner P i erret .Mul t i cs OIO5OO236OI5 Txn 5 Mode X 
Lock U I 0=135165^ 13304 CI =2 

Owner Pierret.Mul tics 010500236015 Txn 5 Mode X 
Lock U 10=135 1654 13304 Cl=0 

Owner P i erret .Mul t i cs OIO5OO236OI5 Txn 5 Mode S 
Lock UID=135165413304 FILE 

Owner P i erret .Mul t i cs OIO5OO236OI5 Txn 5 Mode IX 



! dm_1ock_status -he 

1 ock_seg 
header 

lock= 142970279124797489152 

n_l ock_segments= 1 

lock_seg_size= 4096 

max_l ock_segments= 100 
n_transact ion_table_entr ies= 32 

n_hash_table__entr i es= 256 

hash_mask= 377© 
f ree_l i st_ptr 

seg_inx= 1 

offset= 578 
transaction_tab1e_of f set= 16 

hash_table_offset= 272 

n_lock_b1ocks= 588 

lock_array_of f set= 566 



Spratt. Mul tics 017400343566 Transaction 3 
Lock U I 0=000000000001 Cl=-1 
Owner Spratt. Mul tics 017400343566 Mode IX 
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Name: dm__send__request 
SYNTAX AS A COMMAND 
dm__send_request keyword {value} 
FUNCTION 

enables administrators to send requests to the data management (DM) daemon to 
perform actions it normally performs through internal interfaces. It is an efficient 
mechanism for administrators to activate operations that require access to dm_daemon__gate_. 

ARGUMENTS 

keyword can be any of the following: 

adjust_tdt, adjtdt 

calls on the DM daemon to scan the transaction definition table (TDT) and to 
abort those transactions associated with dead processes and those that have been 
abandoned. This is the same function that the daemon performs as caretaker of 
the data management system (DMS) upon receiving a periodic wakeup call. 

adjust_tdt_entry value, adjtdte value 

calls on the DM daemon to check on the specified transaction and abort it if it 
belongs to a dead process or if it has been abandoned; value is the transaction 
index associated with the TDT entry. 

adjust_txn value, adjtxn value 

calls on the DM daemon to check on the specified transaction and abort it if it 
belongs to a dead process or if it has been abandoned; value is the unique 
transaction identifier assigned when the transaction was started. 

kill_txn value, kill value 

calls on the DM daemon to expunge the specified transaction from the TDT 
without rolling it back or committing it; value is the unique transaction identifier 
assigned when the transaction was started. Any DM files modified by the 
transaction may be left inconsistent, so use this request only as a Is^t resort 

new_proc 

calls on the DM daemon to do a new_proc. This request is useful for setting the 
daemon to use a newly installed version of DMS. 

new_process_notifications, notify 

calls on the DM daemon to send a dm_shutdown_scheduied_ IPS to the proc^ 
sending this request, which implies that the process logged in after the Multics 
shutdown was scheduled. 
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shutdown 

calls on the DM daemon to schedule a DM shutdown coinciding with the 
scheduled Multics shutdown (see the dm_system_shutdown command). This keyword 
enables a Multics operator to shut down data management using the reply operator 
command. Administrators should use the dm_system_shutdown command, as it 
affords the full range of shutdown specifications. 

ACCESS REQUIRED 

You must have re access to dm_admin__gate_. 



Name: dm ^set journal stamps 

SYNTAX AS A COMMAND 
dm_se t_J our nal_s tamps 
FUNCTION 

sets the time stamp for all journals currently in use to the time at which the 
conunand is invoked. 

ACCESS REQUIRED 

You need re access to dm_admin_gate_. 

NOTES 

The effect of altering the time to the present subverts the write_ahead_log (WAL) 
protocol, which guarantees that modified control intervals of protected data management 
(DM) files are not written to disk until their before images have been safely stored in 
a before journal. 

Without the protection imposed by the time stamp, sync-held pages (as modified 
control intervals are called when they are detained in main memory) can be flushed to 
disk prior to their before images. In the event of a system crash without emergency 
shutdown (ESD), some before images may not be available on rollback during recovery. 

You may have to invoke this command if before journals become damaged, preventing 
transactions from being committed, or if there is an unusually large number of 
sync-held pages, stalling system performance. This command keeps the system running 
instead of shutting it down; use it only as a last resort 
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Name: dm set system dir | 

SYNTAX AS A COMMAND | 

dm_set_system__di r path {-control_args} | 

FUNCTION I 

sets the per-system directory for the user process, so that when you invoke Data | 

Management for the first time in your process (setting off a first-reference trap), | 

your process will automatically attach to this directory. | 

ARGUMENTS | 

path 

is the pathname of the directory to be used as the per-system directory for test 
purposes. 

CONTROL ARGUMENTS | 

-brief, -bf | 

suppresses a message confirming that the directory was setup as requested. | 

-long, -Ig I 

causes a message to be printed confirming that the directory was setup as | 

requested. This is the default | 

NOTES I 

The directory established by this command should only be used for test purposes. For 
normal operations, the per-system directory is >site>E)ata_ManagemenL 

If your process is already attached to a per-system directory, you will be instructed to j 

do a user shutdown (dm_user_shutdown command) before you can successfully setup a | 

system directory with this command. i 
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I Name: dm system shutdown 

I SYNTAX AS A COMMAND 

I dm__system_shutdown {-control_arguments} 

I FUNCTION 

schedules a shutdown of Data Management. The DMS can be specified by the 
pathname of the per-system directory, i.e., the directory in which it resides. If no 
pathname is specified, a shutdown is scheduled for the DMS being used by the 
process from which the command is issued. All processes using this DMS are notified 
of the scheduled shutdown via the dm_shutdown_scheduled_ IPS signal. 

I A DMS shutdown can be scheduled to prevent further activity in the current 

I invocation. It can also be used to reduce the time of recovery during the next DMS 

I initialization. 

I A shutdown of DMS occurs in five stages, usually, but not necessarily, in the 

j following sequence: 

I 1. User Warning Time 

j A warning message is printed in each process using the invocation of DMS to be 
I shut down, as follows: 

Data management is shutting down; no new transactions 

will be allowed after <begin shutdown time>. Please 

use the dm_user_shutdown command, or, at <user shutdown tlme>, 

a forced shutdown will be executed. Shutdown reason: {SIR} 

I 2. Begin Shutdown Time 

I The DM daemon (Data_Management.Daemon) prevents the start of any new 

I transactions in the DMS invocation. This is considered the beginning of the DMS 

I shutdown. 

I 3. User Shutdown Time 

I A user shutdown is executed in each process still active in the DMS invocation. 
I A message is printed in each affected process, as follows: 

The data management system is shutting down; starting DM user 
shutdown. Shutdown reason: {STR} 

I 4. User Bump Time 

I The DM daemon bumps each process still using the DMS being shutdown. 

I 5. Daemon Lx)gout Time 

I The shutdown completes with the logging out of the DM daemon. 
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The actual occurrence of each stage is governed by the following rules: | 

• If a control argument containing ".time" is specified, that stage is scheduled to 
occur at the specified time. 

• Starting from each specified time, the times for subsequent stages are calculated 
using the specified or default delays, until a stage is reached which has a 
specified time. 

• If user warning time is not specified, then times are calculated backward from | 
the first specified time, using the specified or default delays, until the first stage | 
is reached. | 

• If no times are specified, the user bump time defaults to the scheduled Multics 
shutdown time, and all other stages are calculated from there using the specified 
or default delays. 

• If no times are specified and there is no Multics shutdown scheduled, an error i 
message is returned. i 

CONTROL ARGUMENTS i 

-dm_system_directory PATH, -dmsd PATH i 

is the pathname of the per-system directory in which the DMS to be shut down j 

resides. There may be several invocations of DMS in the per-system directory; i 

the one selected is the one for the current bootload at the AIM classification of i 

the caller. If no pathname is specified, the DMS invocation in use by the proc-ess • 

is scheduled for shutdown. If no pathname is specified and the process is not i 

currently using an invocation of DMS, an error message is returned, and no other j 

action is performed. i 

-reason STR 

is the reason why the DMS is being shut down. The stated reason appears in the 
messages notifying users at user warning and user shutdown times. If this control 

argument is not specified, a prompt is issued for the reason. STR can be a 
maximum of 64 characters and must be quoted if it contains whitespace. 

-user_warning_time TIME, -uwtm TIME 

specifies user warning time. TIME may be absolute or relative to the time at 
which the dm_system_shutdown command is invoked, and must be in a form 
acceptable to the convert_date_to_binary_ subroutine. If no user warning time is 
specified, it is calculated back from begin shutdown time, using the specified or I 
default begin shutdown delay. i 

-begin_shutdown_delay DELAY, -bsd DELAY i 

specifies the time period between user warning and begin shutdown. DELAY must i 

be in a form acceptable to the convert_date_to_binary_ subroutine. If begin i 

shutdown time is not specified (see below), it is set by calculating forward from i 

user warning time, using DELAY. If DELAY is not specified, it defaults to the i 

begin-shutdown-delay time in the configuration file for the DMS being shutdown, i 
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~begin_shutdown_time TIME, -bstm TIME 

specifies begin shutdown time. TIME may be absolute or relative to the time at 
which the dm_system_shutdown command is invoked, and must be acceptable to 
the convert_date_to_binary_ subroutine. If no begin shutdown time is specified, it 
is calculated forward from user warning time, using the specified or default begin 
shutdown delay. 

-user_shutdown_delay DELAY, -usd DELAY 

specifies the time period between begin shutdown and user shutdown. DELAY 
must be in a form acceptable to the convert_date_to_binary_ subroutine. If user 
shutdown time is not specified (see below), it is set by calculating forward from 
begin shutdown time using DELAY. If DELAY is not specified, it defaults to the 
user-shutdown-delay time in the configuration file for the DMS being shutdown. 

-user_shutdown_time TIME, -ustm TIME 

specifies user shutdown time. TIME may be absolute or relative to the time at 
which the dm_system_shutdown command is invoked, and must be acceptable to 
the convert_date_to_binary_ subroutine. If no user shutdown time is specified, it 
is calculated forward from begin shutdown time, using the specified or default 
user shutdown delay. 

I -user_bump_delay DELAY, -ubd DELAY 

I specifies the time period between user shutdown and user bump. DELAY must be 

j in a form acceptable to the convert_date_to_binary_ subroutine. If user bump 

I time is not specified (see below), it is set by calculating forward from user 

I shutdown time using DELAY. If DELAY is not specified, it defaults to the 

I user-bump-delay time in the configuration file for the DMS being shutdown. 

I -user_bump_time TIME, -ubtm TIME 

I specifies user bump time. TIME may be absolute or relative to the time at which 

I the dm_system_shutdown command is invoked, and must be acceptable to the 

I convert_date_to_binary_ subroutine. If no times are specified (i.e., no control 

I argument specifying TIME is used), user bump time defaults to the scheduled 

I Multics shutdown time. If some other time is specified, but not user bump time, 

I the specified or default user bump delay is used to calculate forward to user 

I bump time. 

-daemon_logout_delay DELAY, -did DELAY 

specifies the time period between user bump and daemon logout. DELAY must be 
in a form acceptable to the convert_date_to_binary_ subroutine. If daemon logout 
time is not specified (see below), it is set by calculating forward from user bump 
time using DELAY. If DELAY is not specified, it defaults to the daemon-logout-delay 
time in the configuration file for the DMS being shutdown. 

-daemon_logout_time TIME, -dllm TIME 

specifies daemon logout time. TIME may be absolute or relative to the time at 
which the dm_system_shutdown command is invoked, and must be acceptable to 
the convert_date_to_binary_ subroutine. If daemon logout time is not specified, it 
is set by calculating forward from user bump time, using the specified or default 
daemon logout delay. 
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ACCESS REQUIRED 

You must have re access to dm_admm_gate_ to execute this command. 
EXAMPLES 

Suppose a Multics shutdown is scheduled for 8:00, and all default delays are five 
minutes, the command 

dm_system_shutdown "bsd 20m in 

would result in a shutdown of data management in five stages, as follows: 

user warning: 7^30 (specified delay) 

begin shutdown: 7:50 (default delay) 

user shutdown : 7^55 (default delay) 

user bump: 8:00 (default time) 

daemon logout: 8:05 (default delay) 

while the command 

dm_system__shutdown -uwtm SsOO -ustm 6:10 -ubtm 6:00 

would result in a shutdown of data management in five stages, as follows: 

user warning: 5:00 (specified time) 

begin shutdown: 5:05 (default delay) 

user bump: 6:00 (specified time) 

daemon logout: 6:05 (default delay) 

Since user shutdown is scheduled after user bump, it is not executed. 



Name: dump^firmware 

SYNTAX AS A COMMAND 

dump_f i rmware path mem {addr count} 

FUNCTION 

dumps the contents of a segment containing MPC firmware. 

ARGUMENTS 

path 

is the pathname of the segment containing the firmware. 
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mem 

must be "cs" to dump the control store overlay, "rw" to dump the read/write 
overlay, or "size" to print the locations and lengths of overlays in the module. If 
it is "size," you need give no further arguments; otherwise, give addr and count 

addr 

is the starting address to dump, in hexadecimal, 
coimt 

is the number of words to dump, in hexadecimal. 

NOTES 

If the firmware segment to be dumped is for an MSP800 device adapter unit (DAU), 
you must still specify cs or rw, which do€$ not affect the output because the DAU 
has only one memory and no control store. A DAU word contains one eight-bit byte, 
as opposed to the MFC's two eight-bit byte format 



Name: dump^mpc 

SYNTAX AS A COMMAND 

dump_mpc mpc_name {-control^args} 

FUNCTION 

performs a dump of the read/ write memory of an MFC and selectively edits the 
dump, the trace table, and MFC and device statistics. 

ARGUMENTS 

mpc_name 

is the name of the MFC to be dumped. This name must appear on an mpc card 
in the config deck. If you omit mpc_name, give -channel. 

CONTROL ARGUMENTS 

-dump 

displays a hexadecimal dump, 
-extend, -ext 

extends the output file if it exists. (Default to overwrite the file) 
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-mpc 

displays MPC error data only. 

-Stat 

displays the MPC and device statistics, 
-trace 

displays an interpreted trace of the MPC. 
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-channel channel_name, -chn channel_name 

specifies a channel name, where channel_name is of the form [iomtag] [channel_no] | 
(i.e., al4). The iomtag field must be a tag of a configured lOM and the 
channel_no must be a decimal channel number. If this control argument is used, 
the mpc_name argument is optional. If both are used, the channel must be 
connected to the MPC specified. 

-output_file {path}, -of {path} 

directs dump output to the segment specified by path. If path is not given, a 
default segment name of [mpc_name] .list is used. If this control argument is not 
given, the default is to direct output to your terminal. 

-long 

formats output for devices with 132 columns or more. The default is based on 
output type and can be used to override the file output default 

-short 

formats output for devices with fewer than 132 colums. The default is based on 
output file type and can be used to override the file output default. 

ACCESS REQUIRED 

You must have re access to rcp_priv_ to use the dump_mpc command. 
NOTES 

If neither the -stat, -dump, -mpc, nor -trace control arguments are specified, only 
the MPC and device statistics are displayed. 

Switch 4 on the MPC maintenance panel is used to control tracing in the MPC. 
Tracing is only done if this switch is in the down position. If the trace table is being 
dumped to see the events leading up to a particular error condition, it may be useful 
to place switch 4 in the up position as soon as possible after the error occurs. This 
inhibits further tracing of I/O in the MPC and reduces the chances of losing trace 
data caused by the table wrapping around before the dump can be taken. 
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Name: dump partition 

SYNTAX AS A COMMAND 

dump_part i t i on pvname partname offset {length} {-control_args} 

SYNTAX AS AN ACTIVE FUNCTION 

[dump_parti t ion pvname partname offset {length}] 

FUNCTION 

displays data from a named disk partition. By default this data appears in octal, four 
words per line, although other output formats can also be selected. See also the 
clear_partition and list_partitions commands. As an active function, dump_partition 
returns the contents of the specified words in octal, separated by spaces. 

ARGUMENTS 

pvname 

is the name of the physical volume on which the partition to be dumped exists, 
partname 

is the name of the partition to be dumped. It must be four characters or less in 
length. 

offset 

is the octal offset at which to begin dumping, 
length 

is the number of words to be dumped. If not supplied, one word is dumped. 
CONTROL ARGUMENTS 
-bed 

produces data including the BCD character representation, 
-long, -Ig 

produces data in long form, similar to dump_segment -long. 

-no_header, -nhe 

suppresses the header. 

-short, -sh 

produces data in short form, similar to dump_segment -short. 
ACCESS REQUIRED 

You need access to the phcs_and hphcs_ gates. 
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Name: ed installation parms 

SYNTAX AS A COMMAND 
ed_instal lation__parms {path} 
FUNCTfON 

edits installation_parms and rate_structure segments. Normally, the segments edited 
should be those in the directory >system_control_l. 

ARGUMENTS 

path 

is the pathname of an installation_parms segment If path is not given, a segment 
named installation_parms, in the working directory, is edited. The segment is 
created if it does not already exist. If the installation_parms segment defines 
multiple rate_structures, then segments named rate_structure_N (where N is a digit 
in the range 1 through 9) in the same directory as installation_parms are edited. 
Editor requests allow the user to switch between installation_parms and the 
rate_structure segments within one invocation of the editor. The entire set of 
segments is edited as a single unit in order to maintain consistency among them. 
All editing is done with temporary copies of these segments; the actual segments 
are updated only by the "w" request described below. 

NOTES 

After this command is invoked, the editor enters its main request loop, and prompts 
the user with the message "type". To return to this request loop from any editor 
query, press the QUIT key and invoke the "program_interrupt" command. Certain 
operations of the editor are defined as critical, as they may require updating many 
interdependent fields. If the user attempts to return to the request loop using QUIT 
and program_interrupt when such an operation is taking place, the editor asks the user 
to confirm the abandonment of the operation. The user may elect to restart the 
interrupted operation. After an abandonment, it may be necessary to retype a number 
of tables, or quit the editor and redo the editing. 

If the user is editing multiple rate_structures, then the following notes apply. When 
editing any segment except installation_parms, the user is said to be editing a 
rate_structure, and is limited in the operations which may be performed. In general, it 
is po^ible to change the pricing information of the rate_structure, but not values 
(such as device names) that affect all rate_structures. In addition, there are items 
specific to installation_parms that cannot be accessed while editing a rate_structure. 
See "Notes on Rate Structure" for details. 
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Some of the requests accept keywords. If the keyword is not given with the request, 
the system prompts with the message "id"; the system administrator then responds with 
one of the keywords described below. At this point, the system either prints out the 
current value of the item or prompts for a new value. (See "Example" at the end of 
this command description.) All requests, keywords, and values can be typed ahead, 
avoiding the prompting messages. In several cases, certain typed ahead values alter the 
operation of the request, causing it to operate on a subset of the data that it 
normally operates on. See the descriptions below for details. 

LIST OF REQUESTS 

The edit requests for the ed_installation_parms command are listed below, 
add XX, a XX 

adds new items to the entry specified by the XX keyword. This request may only 
be used for device_prices, config_table, rate siructure_names, and resources entries. 
(See "Keywords" below.) 

change XX, c XX 

allows an entry, or a portion of an entry, specified by the XX keyword to have 
its value changed. (See "Keywords" below.) 

copy 

prom.pts for an existing rate structure name and copi^ pricing information from 
that rate_structure to the one being edited. 

default 

sets all entries in the installation_parms segment to default values. Requests of the 
form <release name>_default (e.g., mrlO.O_default) are also provided, with any 
release in which new parameters have been added to installation_parms, to 
initialize just the new parameters. See the installation instructions for the release, 
for more information. When specified while editing a rale_structure, the default 
request causes pricing information from the rate_structure named "default" (the 
one in installation_parms) to be copied to the rate_structure being edited. 

help {long}, h {long} 

prints a summary of available requests and keywords. Normally, only the primary 
name of each keyword is printed. If the long argument is given, then the 
keyword abbreviations are also printed. 

print XX, p XX 

prints the entry specified by the XX keyword. (See "Keywords" below.) 
retype XX, r XX 

allows all portions of an entry specified by the XX keyword to be replaced. (See 
"Keywords" below.) 

w 

writes the changes that have been made back into the input segments; all editing 
is done on temporary copies. 
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q 

quits from editor. Must be preceded by a "w" request to save editing. 

rate_structure RS, rates RS 

specifies that subsequent editor requests are to affect the pricing information of 
the rate_structure RS. The installation_parms segment is referred to as rate_structure 
"default". The site may change this or any rate structure name. The single 
character RS "." always refers to installation_parms, even if the name has been 
changed from "default". To return to editing installation_parms, type the request: 
"rate_structure .". If RS is omitted, the name of the current rate structure is 
printed. 

verify, v 

performs certain verifications of the integrity of the installation_parms and 
rate_structure_N segments. Most checks are designed to detect inconsistencies 
between installation_parms and rate_structure segments. If -force, -fc, force, or 
fc is typed on the same line as the verify request, ed_installation_parms forces 
table consistency, zeroing prices for affected entries. The user is notified of each 
such alteration. 

UST OF KEYWORDS 

The various keywords and abbreviations that can be used in requests are 
summarized below. 

abs_cpu_default_limit, abscpudf 

default absentee CPU time limit (in seconds), for each queue. These default limits 
are used when no time limit is specified by the user who enters a job in one of 
the background absentee queues. This parameter is included among those selected 
by the abs_queue_parameters keyword, described below. 

abs_cpu_max_limit, abscpumx 

maximum absentee CPU time limit (in seconds), for each queue and shift. These 
limits allow jobs with high CPU time limits (either specified by the user or 
determined by the abs_cpu_default_limit parameter) to be run during lightly-loaded 
shifts, by specifying the longest-running jobs, from each queue, that will be 
permitted to log in during each shift. This parameter is included among those 
selected by the abs_queue_parameters keyword, described below. 

abs_default_queue, absdfq 

default absentee queue for submission of jobs by the enter_abs_request, pll_abs, 
etc. commands. This parameter may have a value in the range 1 to 4 and 
defaults to 3 unless changed by the system administrator. 

abs_timax 

absentee timax per queue (in microseconds). This parameter is among those 
selected by the abs_queue_parameters keyword, described below. 
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abs_queue_parameters, abs_ 

absentee timax, per queue (in microseconds), default absentee CPU time limit, and 
maximum absentee CPU time limit, the latter for each shift, and the latter two 
for each queue and in seconds. These parameters can also be selected individually, 
by keywords described above. 

access_ceiling, acce 

maximum sensitivity level that may be used, and all categories that may be used. 
Categories are specified by an octal string, levels by a decimal digit. 

all 

every entry. This keyword may only be used with the print or retype requests. 
all_structures 

every entry of installation_parms and every rate_structure. This keyword has the 
effect of "all" for installation_parms, and "rates" for all rate_structures. 

authentication, auth 

default level of security for volume authentication under RCP Resource Management. 
Acceptable values for this keyword are: 

none 

do not authenticate volume labels on mount requests, 
nominal 

authenticate volume labels via an algorithm that rejects volumes only if they 
are obviously incorrect. Additionally, allow manual authentications of "***" 
(as an alternative to typing the correct authentication code) to authenticate a 
volume whose identity is in doubt. 

automatic 

authenticate volume labels via an algorithm that accepts volumes only if they 
are obviously correct. Does not allow manual authentications of "»*♦" to 
authenticate a volume whose identity is in doubt (requires the operator to 
type the correct authentication code). 

Automatic authentication means that the system checks IBM and ANSI 
magnetic tape volumes for an authentication code in the tape label that 
matches the tape label name. Such volumes created on Multics meet this 
requirement. IBM and ANSI tape volumes created on other systems require 
manual authentication when automatic authentication is in effect. 

manual 

require operator to manually authenticate every mount request with the proper 
authentication code. Does not allow an authentication code of "***" to be 
used under any circumstances. 
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auto_registration, auto 

automatic volume registration by RCP. The string "on" sets the flag on; "off" is 
the default. Automatic registration of an unregistered volume is performed when 
the operator allows a user to mount the volume. The volume is registered, with 
default attributes, to the user requesting the volume. This keyword may only be 
used with the change, print, or retype requests. 

category_names, cate 

short (up to eight characters) and long (up to 32 characters) names for up to 18 
access categories. Embedded blanks are allowed in long names only. Category 
names may not be blank. 

config_table, conf 

elements of the configuration table. 

It is required that elements be in order by number of CPUs, within that by 
amount of main memory, within that by amount of bulk store, and within that 
by shift; smaller numbers first 

The config table is automatically sorted after an add, change, or retype operation. 
Duplicate elements and elements containing -1 in the CPU field are deleted by 
this sorL Thus, config elements can be deliberately deleted by changing the CPU 
field to -1. 

A configuration table element consists of 9 numbers, in order, as follows: 



The first four parameters describe the configuration and shift, and the last 5 give 
the load control parameters to be used for that configuration and shift All are 
decimal numbers. 

The mem and bulk parameters are the number of pages of main memory and 
bulk store, respectively. The other two are the number of CPUs and the shift 
number. 

The load control parameters min and max are only used when response control 
(automatic load leveling) is enabled (by the operator command maxu level). Use 
of this feature is not recommended, since the load leveling algorithm is 
unsatisfactory. Nevertheless, values for these parameters must be given when 
entering a config table element. 

The base parameter is the maximum number of load units allowed. The min, max, 
and base parameters may optionally contain a decimal point and a single digit 
fraction (tenths). 
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The absu and absq parameters are the maximum number of background absentee 
users and the number of the lowest priority (highest numbered) absentee queues 
from which jobs are to be taken. (Note that the absu parameter is ignored if the 
number of background absentee users is made a function of interactive load. (See 
"Notes on Absentee Load Control Parameters.") Nevertheless, this parameter must 
always be given when entering a config table element. 

The print request prints the entire config table. 

The retype request completely replaces the entire config table; all of its elements 
must be entered. 

The add request adds a new element to the table. The automatic sort described 
above properly positions the new element 

The change request changes one element The first four parameters (cpu, mem, 
bulk, and shift) are prompted for (or they may be typed ahead). The element 
matching all four of those parameters (exactly) is the one changed. All nine 
parameters of the element must be entered. Thus, the first four parameters must 
be typed twice: once to locate the element to be changed, and once to give new 
(or possibly the same) values to those parameters. 

When entering an element, for the retype, add, or change request the nine 
parameters must be typed, as decimal numbers, in the order shown above. Each 
parameter is prompted for; the prompting may be avoided by typing all nine 
parameters of the element in response to the prompt for the first one (CPUs). 

cwe_count, cwec 

count parameter of the terminal channel wakeup loop detector. If a user causes 
more than cwe_count interactions within cwe_time while logging in, the channel is 
hung up. An interaction occurs every time the Answering Service is notified of 
an event for the terminal channel. The number of interactions perceived by the 
Answering Service is typically the same as the number of input lines (terminated 
by a newline character) entered by the user. The default value for this parameter 
is 10. 

This loop detector protects the Answering Service from overload due to accidental 
or malicious generation of a large number of wakeups in rapid succession by 
devices such as intelligent terminals. If this is a problem at the site, the system 
administrator should establish the smallest possible ratio of cwe_count/cwe_time 
that still allows high-speed channel users to log in. 

The administrator should estimate the maximum number of wakeups which could 
reasonably occur in a burst For example, a hardwired terminal might generate 
five wakeups in quick succession: hangup, dialup, answerback, login line, and 
password line. It would therefore be imprudent to set cwe_count to a value less 

than 5 on a system having hardwired terminals and answerback reading enabled. 
The value of cwe_time would be set according to the fastest channel configured 
at the site. 
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cwe_time, cwet 

time parameter of the channel wakeup error loop detector in seconds. Default 
time is 3 seconds. See also the description of cwe_count above. 

default_pdir_seg_quota, df_pdsq 

process directory segment quota. The default is the value used at system startup. 

default_pdir_dir_quota, df_pddq 

process directory directory quota, the default value is 1000. 

device_prices, devi 

names and prices (dollars per hour, for each shift) for each of up to 16 

miscellaneous devices (teletype channels, high-speed channels, tapes, etc.). For the 
print request, if the name of a device is typed ahead on the input line after the 
device_prices keyword, the prices for that device are printed; otherwise the prices 
of all devices are printed. For the retype request, the name of each device is 
typed and new prices are requested for all shifts. 

device_names, devname, devn 

names of the miscellaneous devices. Allows changing the name of an existing 
device or printing the names of all the defined devices. Changing a device name 
to devN, where N is a number from 1 to 16 indicating the location of the device 
in the table, has the effect of deleting the device, since unused device table 
locations contain names of that form. If a deleted device is the last one in the 
list, the list is shortened by one. 

Charging for certain devices is built into the system. These devices m.ust be 
defined in the device table, with their names spelled exactly as the system expects 
to find them. These devices are defined automatically by the default request A 
warning message is printed by the print device_prices and print devnames requests 
for any of these devices that is not defined. 

devices, device 

names and prices (dollars per hour, for each shift) for each of up to 16 
misceiianeoos devices. For the print request, if the name of a device is typed 
ahead on the input line after the devices keyword, the prices for that device are 
printed; otherwise the names and prices of all devices are printed. For the retype 
request, allows the user to enter new prices for the system defined devices, and 
enter a new set of site-defined device names and prices. For the add request, 
allows the user to define a new device. 

f oreground_cpu_def ault_limit, f gcpudf 

default CPU time limit (in seconds) for the foreground absentee queue. This limit 
is used when no time limit is specified by the user who enters a job in the 
foreground absentee queue. 

fpe_count, fpecount, fpec 

count parameter of the fatal process error loop detector. Default is 3. If 
interactive users get fpe_count fatal process errors within fpe_time, they are 
considered to be in fatal process error loops and are logged out 
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fpe_time, fpetime, fpet 

time parameter of the fatal process error loop detector. Default is 1 minute. 

idle_time_constant, idle 

time over which moving average of foreground load is taken, for use in adjusting 
maximum background absentee users (abs_maxu). Default is 15 minutes. 

inactive_time, inac 

number of real-time seconds a process may remain blocked before being bumped 
for inactivity. 

installation_id, inst 

installation name, city, and state (maximum of 32 characters). Example: 

Company, City, State 



level_names, leve 

short (up to eight characters) and long (up to 32 characters) names for up to 
eight sensitivity levels. Embedded blanks are allowed in long names only; "." 
means leave name blank (level 0 only). 

log_parameters, log_ 

number of pages (1 to 63) to which ring 0 syserr log may grow before being 
copied. A value of -1 means disable automatic copying; 0 means use default 
value. 

login_time. logi 

number of real-time seconds in which login must be completed. 
max_abs 

per-shift upper limit in the abs_maxu equation. See "Notes on Absentee Load 
Control Paramaters" and "Notes on Shift and Queue Specification" below. 

max_qres 

per-shift and per-queue upper limit in the qres equation. See "Notes on Absentee 
Load Control Parameters" and "Notes on Shift and Queue Specification" below. 

min_abs 

per-shift lower limit in the abs_maxu equation. See "Notes on Absentee Load 
Ontrol Parameters" and Notes on Shift and Queue Specification" below. 

min_qres 

per-shift and per-queue lower limit in the qre-s e-quation. See "Notes on A.bsentee 
Load Control Parameters" and "Notes on Shift and Queue Specification" below. 

new_proc_change_auth 

controls the use of the -auth control argument to the new_proc command. If this 
parameter is set on, users can use the -auth control argument. If this parameter 
is set off users cannot use the -auth control argument. 
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The -auth control argument to the new_proc command permits users to create a i 

new process at a different access authorization. This feature can be used by i 

subverting "trojan horse" programs to gain access to information at inappropriate i 

levels. The feature should be disabled by security conscious sites. Users can i 

change authorization by disconnecting and then logging in using the -auth control i 

argument to the login command. i 

operator_inaclivity_limit i 

time limit (in number of seconds) imposed on operator inactivity. Operators who i 

enter no input for more than the specified number of seconds are automatically i 

signed out. The default value is zero (specifying no time limit). i 

password_change_interval, pwci 

specifies the maximum time, in days, that a password can be used before it must 
be changed. If a password is used after the expiration date, an error message is 
printed. The user must use the -change_password option to the login command to 
change the password. If this parameter is set to zero, passwords will not 
automatically require change. The default value is zero. 

password_expiration_interval, pwei | 

specifies the maximum time, in days, that a password can remain unused. If used | 

after the specified period of non-use, the login is denied and the user must seek j 

administrative aid to revalidate the password. If this parameter is set to zero, | 

passwords do not automatically expire after a period of non-use. The default is | 

zero. The administrator can use the new_user command to revalidate the | 

password. | 

password_gpw_length, pwgl 

specifies the length of passwords generated by the -generate_password login 
option. It must be between 5 and 8. The default is 6. 

password_min_length, pwml 

specifies the minimum length (in characters) for a user-supplied password. It must 
be between 3 and 8, or 0. If it is zero, password length is not checked. This 
parameter applies only to new passwords: existing passwords are not checked. The 
default is zero (no check). 

pct_abs 

percent of idle units to be made available to background absentee jobs. Used in 
the abs_maxu equation. See "Notes on Absentee Load Control Parameters" and 
"Notes on Shift and Queue Specification" below. 

pct_qres 

percent of absentee slots to be reserved for each queue. Used in the qres 
equation. See "Notes on Absentee Load Control Parameters" and "Notes on Shift 
and Queue Specification" below. 
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prices 

prices of disk storage (per page-second or page-30-days), per-month registration, 
and per-shift prices of CPU time (dollars/ virtual CPU hour), connect time (real 
hours), terminal I/O operations (kilo lines), and memory usage (kilo memory 
units). 

The change request allows the user to specify a shift and set the CPU, connect 
time, terminal I/O, and memory prices. The retype request asks for the disk and 
registration prices, and then optionally asks for all other prices for each shift. 

queue_prices 

prices for absentee virtual CPU time (dollars/ virtual CPU hour), absentee memory 
usage (dollars/kilo memory unit), and I/O daemon usage (dollars/kilo lines), for 
up to four queues. 

rate_structure_names, rate_structure_name, rsn 

allows changing the name of a rate_slructure, printing the names of the defined 
rate structures, or adding a rale_structure. 

rates 

all pricing fields: device_prices, prices, queue_prices, resource_prices. 

I require_operator_iogin 

I controls the operator identification and authentication option. The value "yes" 
j requires operators to use the sign_on command before entering commands; the 
I value "no" specifies that there will be no such requirement. The default value is 



resources, resource 

names and prices of resources for which users are to be charged. For the print 
request, if the name of a resource is typed ahead on the input line after the 
resources keyword, the price for that resource is printed; otherwise the names and 
prices of all resources are printed. For the retype request, allows the user to 
re-enter all resource names and prices. For the add request, allows the user to 
define a new resource. 

resource_prices, reso 

names and prices of resources for which users are to be charged. The resource 
price list is currently used only for charging for special forms in I/O daemon 
requests. For the print request, if the name of a resource price is typed directly 
after the resource_price keyword, that price is printed; otherwise all the prices are 
printed. For the retype request, the name of each resource is typed and a new 
price is requested. 

resource_names, rscname, rscn 

name of an existing entry in the resource price list. Allows changing the name of 
an existing resource. 
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resource_wait_time, rsctime, rsct 

time interval at which to keep checking for resource availability when an absentee 
job is waiting for a resource and there are no other jobs logging in or ouL 
Default is 5 minutes. 

revalidate | 
the users password is revalidated (after having expired following a period of | 
non-use). | 

rsc_mgmt_enabled, rsc_ 

activation of the RCP Resource Management subsystem. The string "on" sets the 
flag on. Initially this flag is off; it should not be turned off again once it has 
been turned on. This keyword may only be used with the change, print, or retype 
requests. 

shift_table, shif 

shifts for each half -hour of the week. Shifts are numbered 0 to 7. By default, 
the change request changes the shift of a single half hour, specified by day, hour, 
and half hour (see example below). However, if the word "thru" is typed ahead 
on the input line after the first half hour, then a second day, hour and half 
hour are read, and all half hours from the first through the second are set to 
the specified shift (see the example below). 

sus_cpu_time, susc 

CPU time limit imposed on a suspended process. The default is 5 seconds. The 
default handler for the sus_ signal, in a user process, goes blocked and waits to 
be released. If the process fails to respond in this way, and continues running, it 
is destroyed after it has used the specified amount of CPU time (after the sus_ 
signal is sent). 

sus_real_time, susr 

real time limit imposed on a suspended process. The default is 180 seconds. 
Before going blocked, a suspended process sends a wakeup to the answering 
service, specifying the event channel on which it is about to go blocked, and over 
which it can be released. If the proc^ fails to respond in this way within the 
specified interval of real time, it is destroyed. 

titles 

company name and department name single spaced (maximum of 64 characters) 
and double spaced (maximum of 120 characters). Example: 

Company Name, Inc. 

Company Name, Inc. 



tries 

number of login tries allowed before Multics hangs up line. 
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lrm_cpu_time, trmcputime, trmc 

cpu time limit imposed on a process that is being terminated and has been sent a 
trm_ signal. Default is 5 seconds. 

A process being terminated involuntarily by the answering service (e.g., by the 
bump command), as opposed to a process that terminates itself voluntarily (e.g., 
by the logout command), is sent a trm_ signal, and is given a small amount of 
time to terminate itself. The default handler for trm_ signals the finish condition 
in the user's process. 

trm_real_time, trmrealtime, trmr 

realtime limit imposed on a process that has been sent a trm_ signal. Default is 
120 seconds. 

unload_on_detach, unlo 

detached volumes are unloaded automatically. The string "on" sets the flag on; 
"off" is the default. When the flag is off a detached volume remains on its drive 
until the drive is needed for another volume. This flag has no effect when the 
user specifies "-retain all" in the attach description of the volume being detached 
(see the tape_ibm_ module in the Multics Subroutines and 1 10 Modules manual. 
Order No. AG93). This keyword may only be used with the change, print, or 
retype requests. 

update_time, upda 

number of real-time seconds between accounting updates. 

warning_time, warn 

number of real-time seconds between warning (of an automatic logout) and actual 
logout. 

This value also affects the automatic bumping of users prior to a shutdown 
scheduled through the initializer down command (described in Section 4). The 
bump is scheduled for N minutes before the time specified in the down command 
(where N is warning_time divided by 60, rounded up to the next whole minute). 
At that time, all interactive users are bumped (i.e., warned that they will be 
logged out in N minutes), and the login word is changed to prevent further 
logins. 

I validate_daemon_commands 

I controls activation of the secure daemon facility. The string "on" sets the facility 
I on. the string "off" sets the facility off. Initially the facility is set "off." See 
I "Notes On Secure Daemon Facility," later in this command description. 
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NOTES ON RATE STRUCTURE 

The following keywords may be used when editing a rate_structure: all (same as 
"rates"), device_prices, device_names, devices, prices, queue_prices, rates, 
rate_structUTe_names, resource_prices, resource_names, and resources. Further restrictions 
on this set of keywords exist within some requests. For example, none of the 
keywords are allowed to change device or resource names when editing a rate_structure 
because such a change must be reflected in all rate_structures. 

Users must have read access to rate_structure_N segments in >scl when multiple 
rate_structures are in effect In addition, all daemons that charge users for services 
must have read access to the SAT, to determine the appropriate rate_structure for a 
user's project. These access settings are unnecessary when a site is using a single rate 
structure. 

NOTES ON ABSENTEE LOAD CONTROL PARAMETERS 

The installation_parms segment contains a number of parameters that enable the site to 
regulate the background absentee load. (Background absentee jobs are those from the 
four background absentee queues, numbered 1 to 4, as opposed to jobs from the 
foreground absentee queue. The latter are regulated by foreground load control. 

By default, abs_maxu, the number of absentee slots (i.e., the maximum number of 
concurrently logged in background absentee jobs) is a constant, for each shift-configuration 
combination in the configuration table (see below). However, it can optionally be 
made a, function of interactive load. The abs_maxu figure in the configuration table is 
only used when the parameters described immediately below (pct_abs, min_abs, and 
max_abs) have not been set 

Background absentee jobs are intended to occupy idle capacity. The number of idle 
units is computed by the equation: 

idle__units = max_units - n_daemons - n_i nteract i ve 

where max_units is the system maximum units figure for the current shift and 
configuration, as specified in the configuration table, and n_daemons and n_interactive 
are the current number of units occupied by daemon and interactive users, 
respectively. 

Since this figure can fluctuate rapidly as the number of interactive users changes, it is 
smoothed in the following wayt a mcving average of idle units over the last M 
minutes is kept (where M is the value, in minutes, of the idle_time_constant 
parameter in the installation_parms segment), and the lower of the current value and 
the average value of idle units is used to compute abs_maxu each time an absentee 
login decision is made. This algorithm causes the increase in abs_maxu to lag behind a 
decrease in interactive load, but the decrease in abs_maxu occurs immediately in 
response to an increase in interactive load. 
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The abs_maxu figure is computed by the equation: 

abs_maxu = min (max_abs, max (min_abs, pct_abs * idle_uni ts) ) 

that is, abs_maxu varies between min_abs and max_abs, as a function of pct_abs and 
idle_units. For example, with pct_abs = 10%, max_abs = 6, and min_abs = 1, abs_maxu 
varies between 1 and 6 as idle_units varies between 10 and 60. If idle_units goes 
above 60 or below 10, abs_maxu does not rise above 6 or fall below 1. 

The three parameters max_abs, min_abs, and pct_abs are kept in the installation_parms 
segment, and can have different values on each shift 

It is possible to reserve a portion of abs_maxu for the use of the higher priority 
queues. This avoids delaying jobs from the higher priority queues that are entered into 
the queues after all the slots have been occupied by jobs from lower priority queues. 
Two algorithms are described here: the way the qres figures for each queue are 
computed, and the way all the qres figures are used to determine whether or not an 
absentee job from an individual queue is permitted to log in. 

The number of reserved slots for each queue is computed by the equation: 

qres (q) =min (max_qres (q) , max (mi n_qres (q) , pct_qres (q) * abs_maxu) ) 

where qres(q) is the number of slots reserved for queue q. Thus qres(q) varies 
between min_qres(q) and max_qres(q), as a function of pct_qres(q) and abs_maxu. The 
min_qres, max_qres, and pct_qres parameters are kept in the installation_parms 
segment and have separate values for each queue and each shift. 

The reserved slot facility does not place an absolute limit on the number of jobs 
from any (except the lowest priority) queue. It prevents jobs from lower priority 
queues from logging in if their logging in would leave too few slots available for the 
higher priority queues, but it allows jobs from high priority queues to occupy all of 
the slots and exclude jobs from lower priority queues. The algorithm is as follows: to 
determine if a job from queue q can log in, first reduce the current abs_maxu by the 
number of jobs currently logged in. This gives the number of available slots. (If it is 
zero, no job can log in.) Then, for each queue of higher priority than queue q, if 
the number of jobs currently logged in from that queue is less than qres(i) (where i 
is the number of that higher priority queue), reduce the number of available slots by 
the difference. If there is at least one available slot after that has been done, the job 
can log in. 

NOTES ON SHIFT AND QUEUE SPECIFICATION 

I The max_abs, min_abs and pct_abs keywords of ed_installation_parms define values for 

I each shift. The max_qres, min_qres and pct_qres keywords define value for each 

I queue, in each shift. For these keywords, the print request prints values for all shifts 

I and queues, but the change and retype requests can select particular shift and queue 

j groups to be changed or respecified. 
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For max_abs, min_abs and pct_abs, you can specify which shift to change on a 
change request line, either by using the shift keyword followed by a shift number or 
range of numbers, or by giving a single shift number. The new value can also be 
given on the request line. For the retype request, you can use the shift keyword to 
specify which shift{s) are to be changed, followed by the new values. If new values 
aren't given, they are prompted for. For example: 

type ! c max_abs shift 1 k 
type ! c max_abs shift 2-U 6 
type ! c max_abs 5 
max_abs: shift 5^ ' 7 
type ! r max_abs shift 2-3 
max_abs: shifts 2-3: ! 5 
type ! p max__abs 
max_abs - PER SHIFT 

0123^567 
-1^5567-1-1 

For max_qres, min_qr^ and pct_qrK, you can specify which queue and shift to 
change in a change request line, either by using the queue and shift keywords 
followed by a number or range of numbers, or by giving a single queue or shift 
number. The new value can also be ^ven on the request line. If neither queue nor 
shift keyword is used, then the queue number must be given first, followed by the 
shift number and the new value. If queue or shift number or new value are omitted, 
you are prompted for these values. For the retype request, you may use queue or 
shift keywords to limit retyping to a specified set of queues or shifts. By default, 
retype prom-pte for value for all queues of each shift In a retype request line, 
numeric values not preceded by a queue or shift keyword are treated as new values. 
For example: 



type ! c 


max__qres queue 1-i* 


shift 


0-7 0 








type ! c 


max_qres queue I-3 


shift 


1 3 








type ! c 


max__qres k 1 2 












type ! r 


max_qres shift 2-3 












fr!ax_qres z 


shifts 2-3: queue 




! 








max_qres: 


shifts 2-3: queue 


2: ! 


3 








max_qres: 


shifts 2-3: queue 


3: ! 


2 








max_qres : 


shifts 2-3: queue 


k: ! 


1 








type ! c 


max_qres shift k-S 












queue: 2 














max__qres: 


queue 2: shifts k- 


-5: ! 


3 








type ! p 


max qres 












max qres 


- PER QUEUE AND SH 


I FT 










Q 0 


1 2 


3 


k 


5 


6 


7 


1 0 


3 h 


h 


0 


0 


0 


0 


2 0 


3 3 


3 


3 


3 


0 


0 


3 0 


3 2 


2 


0 


0 


0 


0 


if 0 


2 1 


1 


0 


0 


0 


0 
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I NOTES ON SECURE DAEMON FACILITY 



The secure daemon facility enables administrators to control operator access to daemon 
processes. The administrator must set appropriate access rights on the ACS segment 
associated with the specified daemon. (This procedure is described in the Multics 
Programmer's Reference Manual, Order No. AG91.) When the secure daemon 
facility is set "on," the following actions occur: 

1. If the operator uses the login command to login a daemon, the system will check 
to determine if an access control segment exists for the specified daemon. If no 
ACS siegment exists, the command will not be executed. If the ACS segment 
exists, the system will check to determine if the operator has sufficient access to 
login the daemon. Additionally, the system will check to determine if the selected 
daemon is permitted to login. If the operator or daemon do not have the 
required access, the daemon is not logged in. 

2. If the operator uses the reply, quit, or logout command to communicate with a 
daemon, the system will check the access control list to determine if the operator 
has sufficient access to perform the specified operation. If the operator has not 
been granted sufficient access, the command will not be executed. 

I See the Multics System Administration Procedures manual, Order No. AK50 for 
I additional information on the secure daemon facility. 

EXAMPLES 

In this sample, the system administrator first prints the current value of the "warning 
time" variable (the number of seconds before shutdown that a user is warned), and 
then changes the value. Finally, the change is made to the original installation_parms 
segment (w), and the administrator exits (q). (Lines, or portions of lines, typed by the 
administrator are preceded by " "). 

! ed_ i nsta 1 1 at i on_parms 



type ! c shif Frl l8 00 thru Men 07 30 5 
type ! w 
type ! q 
<ready> 

This defines shift 5 to start at 1800 Friday and end at on 0800 Monday. 



type !p 

id Iwarni ng_t ime 
warni ng_t ime: 300 sec. 
type !c 

id Jwarni ng_t ime 
warning time (sees) ! 



6000 



type !w 
type !q 
<ready> 



ed installation parnis 
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Name: ed mgt 

SYNTAX AS A COMMAND 
ed_mgt {path} 
FUNCTION 

allows the system administrator to edit a copy of the master group table (MGT). The 
MGT defines work classes and load control groups, which determine the number of 
users from each group that are permitted to log in, and the percentage of system 
resources that they are allocated while logged in. A complete discussion of load 
control groups and work classes is found in the Multics System Administration 
Procedures manual. Order No. AK50. 

ARGUMENTS 

path 

is the pathname of the copy of the MGT to be edited. If the pathname is not 
given, the default is the segment MGT.mgt, in the working directory. If the 
segment does not exist, it is created and initialized. (The suffix, mgt, is not 
assumed, or required, by ed_mgt — the MGT to be edited may have any name. 
However, the suffix is required by the install command.) Normal practice is to 
edit the MGT.mgt segment in >udd>SysAdmin>admin and then install it, using the 
install command. The install command merges it with the system copy in the >scl 
directory, preserving the current load figures in the system copy. The system copy 
of the MGT should never be edited directly. (The load_ctl_status command can 
be used to display the contents of the system copy.) 

NOTES 

This command operates in r»ponse to requests from the user. Most of the requests 
have a full name and one or more abbreviated names. Either the full names or the 
abbreviations may be typed. Many of the requests take one or more arguments. If 
these arguments are not supplied on the same line as the request, ed_mgt prompts the 
user for them. Multiple complete requests (including their arguments) may be typed 
on the same line. (The line may end with an incomplete request, i.e., with some 
arguments missing.) The only limit on the number of requests that may be typed on 
one line is the length of the buffer used to read request lines (128 characters). 

One of the requests, change, puts ed_rogt into "change mode": once in this mode only 
change requests are recognized (other ed_mgt requests are not recognized). To return 
to ed_mgt request level from change mode, it is necessary to type "." or "*". The 
prompting message for the next request, at request level, is "type"; in change mode, it 
is "code". 
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The user may issue a quit signal, and then type the program_interrupt (pi) command, 
to return to ed_mgt request level. This is useful to abort the output of certain 
requests that may produce a large amount of output. Unless it is issued while a 
request that modifies the MGT is actually being executed, the quit-pi sequence has no 
adverse effects on the contents of the MGT. 

The MGT consists of a header and an array of entries. The first 16 are always work 
classes 1 through 16; the rest are site-defined load control groups. Some requests 
operate on only one of these two entry types; others operate on both types. There is 
a conceptual pointer that always points to one of the entries. There are several 
requests that move this pointer. Some requests operate only on the entry specified by 
the pointer; others operate on all entries of one of the types, or on all entries in the 
MGT. 

Requests that operate on more than one entry do not move the pointer. Requests that 
do move the pointer print the type and name of the entry to which it is moved 
(unless there are further requests on the line after the one that moved the pointer). 
When ed_mgt is entered, the pointer is set to the first load control group (the 17th 
entry). If there are no groups (which is the case if the MGT did not exist), then 
ed_mgt prompts the user for the name and parameters of a group to add. 

LIST OF REQUESTS 

The ed_mgt requests, and their abbreviations, are listed below. Detailed descriptions 
follow, in the same order as the list. The codes accepted in change mode are not 
included here; they are listed within the detailed description of the change requesL 

find, f 

next, n 

- (minus sign) 

top, t 

add, a 

del ete 

def i ne 

redef i ne 

undefine 

print, p 

pall, pa, p''^ 

write, w 

quit, q 

verify, v 

global_change, gc 

change, c 



NOTES ON REQUEST DESCRIPTIONS 

For convenience, the following format is used in the request descriptions. 

1. If a request has one or more short names, they are listed below the long name. 
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2. Any arguments the request takes are shown only with the long name. 

3. The shift_spec argument used by the define, redefine, and undefine requests is 
described under the change request, which also uses it 

LIST OF DETAILED REQUEST DESCRIPTIONS 

find entry, f 

moves the pointer to the entry (group or work class) whose name is given, and 
prints its type and name. If the entry does not exist, the pointer is not moved. 

next, n 

moves the pointer to the next entry, and prints its type and name. If the pointer 
is already at the last entry, it remains there, and "EOF" is printed. 

- (minus sign) 

moves the pointer to the previous entry and prints its type and name. If the 
pointer is already at the first entry, it remains there, and "TOP" is printed. 

top, t 

moves the pointer to the first entry and prints its type and name. 

add group constant work_class, a 

adds a new group, after the last group in the MGT. The first argument is the 
group name, which can be a maximum of eight characters, and must begin with a 
capital letter. The second argument is the constant in the maximum primary users 
equation for the new group. (The group is allowed at least this number of 
primary users, on any configuration of the system.) The third argument is the 
work class that all users in this group (both interactive and absentee) are assigned 
to, on all defined shifts. After the group has been added, the change request can 
be used to modify its parameters or add new ones. 

The pointer is set to the new group. If the group already exists, a message to 
that effect is printed, and the pointer is set to the existing group. The add 
request can only add groups. Entries for the 16 possible work classes always exist, 
although the unused ones are marked as undefined. The change request can be 
used to define an undefined work class. An attempt to add one of the 16 work 
classes produces an error message, but leaves the pointer set to that work class. 

delete 

deletes the current load control group, if the current pointer points to a load 
control group. If the current pointer points to a work class, an error message is 
printed. See the note under the verify request regarding restrictions on deleting 
groups. 
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define shift_spec {like shif t_number} 

sets the group and work class values for the specified shifts to valid, consistent 
values. If the optional "like shift_number" parameter is given, the values are set 
to the respective values from the specified shift. Otherwise, the values are set to 
defaults: all groups are placed in work class 1; work class 1 is given 100% of 
available virtual CPU time; its scheduling mode is set to normal; and normal 
scheduling mode is set to percent. If the specified shifts are already defined, an 
error message is printed, and no changes are made. For example, to define shifts 
2 through 4 to be exactly like shift 1, type: 

define shifts 2-k like shift 1 



redefine shift_spec {like shift_number} 

operates like the define request, except that it can be used to change the values 
for a shift that is already defined. 

undefine shift_spec 

sets the group and work class values for the specified shifts to null values, and 
undefines all work classes on the specified shifts. It is recommended that shifts 
not used at the site be undefined. This minimizes the output produced by the 
pall request and prevents the verify request from printing extraneous error 
messages. 

print, p 

prints all information about the current entry. 

pall typel type2 .... pa, p* 

prints all information about some or all entries or the header. When no type 
arguments are given, the default is to print all information in the MGT. Valid 
type arguments are: 



total, tot 

print header 

group, leg 

print all load control groups 

work_class, wc 

print all work classes 

xref, cref 

print cross reference showing which groups are in each work class, on each 
shift 

Printing of a cross reference should only be attempted for an MGT that passes 
the consistency tests made by the verify request. The results of a cross reference 
of an inconsistent MGT are unpredictable. 
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write, w 

writes the edited copy of the MGT back into the original. (Editing is performed 
on a temporary copy.) 

quit, q 

exits from ed_mgt. If a write request is not issued before quitting, the editing is 
lost, and the original copy remains unchanged. 

verify max_errors, v 

examines the edited MGT for internal consistency and correctness, and reports 
errors that it finds. The max_errors argument is an integer that indicates how 
many errors are reported before the user is asked if the verify request should be 
continued. This argument is optional; if omitted, a default value of 5 is used. 

Errors usually involve conflicts between group and work class definitions, and 
these fall into repeating patterns, especially since errors are reported separately for 
each shift. Thus, a single editing error can produce a large number of error 
messages, only the first few of which are useful. The output of verify can safely 
be aborted with the quit-pi sequence, but the max_errors argument usually makes 
this unnecessary. After max_errors messages have been printed, the user is asked 
if the verify request should be continued. If the answer is yes, the question is 
repeated every max_errors messages thereafter. 

The verify request detects all errors that cause installation of the MGT to be 
refused, except for one: an attempt to install an MGT that deletes or renames a 
load control group that is currently in use. An in-use load control group is one 
that some logged-in users belong to or one that is named in the SAT as the 
default group for one or more projects. Deleting or renaming such a group is 
not allowed, but this error cannot be detected until the attempt is made to install 
the new MGT. 

In addition, the verify request detects two conditions that are not fatal and do 
not prevent installation of the MGT, but are probably oversights on the part of 
the user: a work class with no groups (and therefore no users) in it, and the sum 
of work class percentages being less than 100% on any defined shift. 

globaLchange entry_type change_arguments, gc 

allows the specified changes to be made to all groups or all defined work classes. 
The entry_type argument may be "group", "leg", "work_class", or "wc". This 
request enters change mode, and accepts a series of code-qualifier-value groups, 
just as the change request does. Each change is made to all entries of the 
specified type before the next change is processed. Values of or for code 
cause an exit from change mode and return to ed_mgt request level. 
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change code qualifiers values c 

puts ed_mgt into change mode, in which successive code-qualifier-value groups are 
read and processed. A code of "." or "*" causes an exit from change mode and 
return to ed_mgt request level. Except for the header codes (prio_sked, 
normal_mode, and shifts), changes are made to the entry pointed to by the 
pointer. (See the global_change request to make changes to all groups or all work 
classes.) Except for one code (absentee), each code applies to only one of the 
entry types. The set of possible qualifiers and values is, in general, different for 
each code. Some of the codes accept no qualifiers and only one value. Most of 
the codes have a full name and one or more abbreviations. Either the full name 
or the abbreviation may be typed. The codes and their abbreviations are listed 
below, grouped according to the entry type to which they apply. Detailed 
descriptions follow. 

Group 
id 

constant, const, con 
numerator, num 
denominator, denom, 
max_prim, maxp, maxu, m 
abs_max, abs. 

Group and Work Class 
absentee 
numl 

denoml , denl 
work_class, wc 
absentee_max 
absentee_mi n 
absentee_pct 

There are several qualifier and value formats and many relationships between the 
two that are common to several of the codes. These are described here, instead 
of being repeated under each code. 

There are three types of qualifiers: the shift specification (shif t_spec), the queue 
specification (queue_spec), and the interactive/absentee indicator (int/abs). There 
are three types of data values: floating point (float), integer (int), and yes/no 
(y/n). 

The ed_mgt command prompts for codes, qualifiers, and values, if they are not 
typed on the same line as the change request. For those codes that accept 
qualifiers, if the code and the values are typed on the same line and the 
qualifiers are omitted, defaults are assumed for the qualifiers. (The defaults are a 
function of the number of values given.) If the values are not typed on the same 
line as the code, then the ed_mgt command prompts for the qualifiers and they 
must be given. For example, the line: 

change work_class 3 • 



Header 

prio_sked, prio 
norma l_mode, norm 
shi f ts 



Work Class 

percent, pet, % 
defined, def 
int_resp, ir 
int_quantum, iq 
resp, r 
quantum, q 
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assumes default qualifiers of "shift all" and "interactive", while the line: 
change worked ass 

makes the command prompt for both the shift specification and the 
interactive/absentee indicator (as well as the work class value). 

The shift specification (shift_spec) has three formats: 

shift s 
shift sl-s2 
shift al 1 

When a single shift number is given (the first format), the values that follow are 
assigned to shifts s, s2, ... sN for as many values as are given, where s2 ... sN 
represents the set of defined shifts whose numbers are greater than s. Shifts for 
which no values are given remain unchanged. 

The second format, giving a pair of shifts (where s2 must be greater than si), is 
followed by one value, which is assigned to shifts si and s2 and to all of the 
defined shifts whose numbers fall between si and s2. Shifts not included in the 
sl-s2 remain unchanged. 

The third format is equivalent to giving the second, where si and s2 are the 
lowest and highest numbered defined shifts, respectively. 

When the shift specification is omitted, and one or more values are typed on the 
same line as the code, the default shifts are a function of the number of values 
given; that is, a single value is assigned to all defined shifts, while each value in 
a group of values is assigned to shift si, s2, ... respectively, for all defined shifts. 

The interactive/absentee indicator (int/abs) can be one of the following: 
interactive, absentee, int, or abs. It is used with the work_class code and may be 
given before or after the shift specification. If it is not given, the default is 
interactive. 

The queue specification (queue_spec) consists of the word "queue" (or "q") 
followed by one or more absentee queue numbers, or the word "none". The 
queue numbers may be in the range 1 to 4. The notation ql-q2 may be used, to 
indicate a range of queues; for example: 

queue I 2 3 
queue 1-3 

are equivalent. This specification is used with the absentee code while changing a 
group. 

Integer values (int) are simply decimal integers. 
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Floating point values (float) may be given for any of the group codes except "id" 
and "work_class". They differ from integer values only in that they (optionally) 
end with a decimal point and a single-digit fraction (tenths), or a two-digit 
fraction (hundredths). 

The yes/no values (y/n) can be represented by a variety of positive or negative 
words: 



yes 

y 

oh 
1 

a 1 1 owed 



no 

n 

off 
0 

not_al lowed 
'^al lowed 



LIST OF DETAILED CHANGE CODE DESCRIPTIONS 
prio_sked y/n, prio 

sets the prio_sked_enabled switch in the header of the MGT. When this switch is 
on, users are placed in the work classes specified in the body of the MGT, and 
those work classes are given the percentages of system resources specified in the 
body of the MGT. When the switch is off, the work class information in the 
body of the MGT is ignored and all users are placed in work class 1; thus, work 
class 1 is given 100% of system resources, effectively disabling the priority 
scheduler. This can be useful to compare system performance with and without 
the priority scheduler enabled and also to recover immediately from the effects of 
having made an unwise change to the MGT, causing undesirable system behavior. 

normal_mode {shifl_spec} MODE, norm 

sets the normal scheduling mode for the specified shifts to MODE, where MODE 
can be "deadline" or "percent" ("pct","%"). This scheduling mode is in effect for 
all work classes whose mode is set to normal (rather than realtime) on the given 
shifts. 

shifts shiftjist 

sets the list of defined shifts (those in use at the site) to the given list The list 
may consist of any combination of single digits or pairs of digits separated by 
hyphens. For example: 

c shifts 1-^ 7 

indicates that shifts 1, 2, 3, 4, and 7 are used. The list of defined shifts is used 
in interpreting the shift_spec parameter that is an argument to a number of the 
ed_mgt requests, and it is used to supply a default shift specification when none 
is given. 

id group_name 

changes the name of the group. See the note under the verify request regarding 
restrictions on renaming groups. 
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constant float, const, con 

is the constant in the maximum primary units equation (described in "Load 
Control Equations and Group Parameters" below). 

numerator float, num 

is the numerator in the maximum primary units equation (described in "Load 
Control Equations and Group Parameters" below). 

denominator float, denom, den 

is the denominator in the maximum primary units equation (described in "Load 
Control Equations and Group Parameters" below). 

max_prim -1, maxp, maxu, m 

The only valid value for max_prim is -1. Normally, max_prim is the lefthand 
side of the maximum primary units equation, and is computed each time a user 
logs in, from the constant, numerator, denominator, and the current system 
maximum units figure. A value of -1 indicates that, instead of being computed 
that way, the maximum primary units figure for this group should be computed 
by deducting from the system maximum units figure the computed maximum 
primary units figures for all the other groups, and giving this group what is left 
over. Thus, only one group may have a max_prim value of -1. 

To remove a -1 max_prim from a group so that its max_prim value is computed 
normally, type a value of zero for max_prim and ignore the resulting warning 
message. 

aKe -rrtov flz-kot oVkC mi-nompv 
L/5 lllCLA 1 IVUL, Uk/>2, l.llli.XtXiil&7\ 

is the constant in the absolute maximum units equation (described in "Load 
Control Equations and Group Parameters" below). 

numl float 

is the numerator in the absolute maximum units equation (described in "Load 
Control Equations and Group Parameters" below). 

denoml float, denl 

is the denominator in the absolute maximum units equation (described in "Load 
Control Equations and Group Parameters" bellow). 

work_class shift_spec int/abs int ... int, wc 

sets the per-shift work classes to which users in this group are assigned. A 
separate set of work class assignments is maintained for interactive and absentee 
processes. If int/abs is omitted, the default is interactive. A work class of zero 
(for both interactive and absentee) should be set for shifts not in use at the site. 

absentee_max float 

is the upper limit in the absenteejimit equation (described in the Notes section 
of the ed_installation_parms command). A value of 3276.7 indicates that no 
absolute upper limit should be imposed. 
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absentee_min float 

is the lower limit in the absentee_limit equation (described in the Notes section 
of the ed_installation_parms command). 

absentee_pct float 

is the maximum percent of absentee slots that may be occupied by users from 
this group. It is used in the absenteejimit equation (described in the Notes 
section of the ed_installation_parms command). A value of 100.0 indicates that no 
percentage limit should be imposed. 

absentee 

The absentee code applies to both groups and work classes, but it has a different 
format for each of the entry types: 

Group: absentee y/n 

sets the absentee_allowed switch, which determines whether absentee jobs for users 
who are normally in this group are allowed to remain in the group or are moved 
to a default absentee group. 

Group: absentee queue_spec 

determines whether or not this group is the default absentee group for one or 
more absentee queues. A queue_spec of "queue none" removes the group from the 
set of default absentee groups. 

The default absentee group feature allows absentee jobs to be put into work 
classes separate from interactive users, either to guarantee or to limit the portion 
of system resources that they consume in competition with interactive users. It is 
possible to put jobs from one or more queues into separate work classes, by 
putting them in separate groups, and assigning those groups to separate work 
classes. 

There may be only one default group for each absentee queue; however, a single 
group may be the default group for more than one queue. 

When the default absentee group feature is used, the absentee_allowed switch 
should be turned off in all groups except the default absentee groups to force 
absentee jobs to be removed from their normal groups and placed in the default 
absentee groups during login. 

Work Class: absentee shift__spec y/n ... y/n 

sets the per-shift absentee_allowed switch of the work class. This switch is 
provided for consistency checking. It should be turned on for those work classes 
in which absentee jobs are expected to run, and off for all others. Then, the 
verify request detects any instances where the parameters of a group assign 
absentee jobs to a work class that is reserved for interactive users. 



2-200 



GB64-00 



ed_mgt 



ed_mgt 



percent shift_spec int ... int, pet, % 

sets the per-shifl minimum percent of the work class. The sum of percentages of 
all work classes, on each shift, must be <= 100%. Work classes must have 
nonzero percentages on any shift on which they are defined. Refer to "Scheduler 
Parameters" below for a more complete discussion. 

max_percent shift_spec int ... int, max_pct 

sets the per-shift maximum percent for the work class. This parameter is 
effective only for non-realtime work classes when the scheduler is operating in 
percent mode. In that case, this parameter represents the maximum percent of 
system resources that may be consumed in aggregate by this work class during 
each shift. A value of 0 means that the work class has no resource limit (this is 
the default). The value specified must be in the range 0 to 100. Refer to 
"Scheduler Parameters" below for a more complete discussion. 

defined shift_spec y/n ... y/n, def 

sets the per-shift defined switch of the work class. All unused work classes 
should be set to undefined on all shifts, and all used work classes should be set 
*o undefined on those shifts that are not in use at the site. 

int_resp {shift_spec} float ... float, ir 

sets die per-shifl interaction response time for the work class. This time is used 

only when scheduling in deadline or in realtime mode. An attempt is made to 

run the process within the specified time, after an interaction. The time is in 

seconds, and is kept in hundredths of a second. The default is 4.00 seconds. 

int_quantum {shift_spec} float ... float, iq 

sets the per-shift interaction quantum for the work class. The quantum is only 
used when scheduling in deadline or in realtime mode. It is the amount of 
virtual CPU time a process in this work class receives, after an interaction, before 
losing eligibility. The time is in seconds, and is kept in hundredths of a second. 
The default value is 0.50 seconds. 

resp {shift_spec} float ... float, r 

sets the per-shift steady state response time for the work class. Tnis time is only 
used when scheduling in deadline or in realtime mode. An attempt is made to 
run the processes in this work class every N seconds, where N is the specified 
response time. The time is in seconds, and is kept in hundredths of a second. 
The default is 32.00 seconds. 

quantum fshift_spec} float ... float, q 

sets the per-shift steady state quantum for the work class.- The quantum is only 
used when scheduling in deadline or in realtime mode. It is the amount of 
virtual CPU time a process in this work class is given before it loses eligibility. 
The time is in seconds, and is kept in hundredths of a second. The default is 
1.00 seconds. 
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mode {shift_spec} NORM/RT 

sets the per-shift scheduling mode for the work class to either realtime mode, or 
to the normal mode in effect for the shift. NORM/RT can be "normal" 
("norm") or "realtime" ("rt"). When realtime mode is used, the deadline scheduling 
parameters — response times and quanta — are used. The response times are 
interpreted as real times, and processes in the work class are run within the 
specified real times, if at all possible. 

NOTES ON SCHEDULER PARAMETERS 

The hardcore scheduler (traffic control) operates in either "deadline mode" or 
"percent" mode, as specified for each shift by the "normal_mode" change code, 
described above. Regardless of the scheduler mode, the scheduler attempts to meet the 
specified responses for realtime work classes. If necessary, processes in realtime work 
classes are given priority over processes in non -real time work classes. Also, among 
processes in realtime work classes, those whose response is late are given priority over 
those whose response is not late. The general effect of this is that realtime work 
classes are given priority over non-realtime work elates, and realtime work classy 
with shorter values of resp are given priority over realtime work classes with longer 
values. 

The distribution of CPU resources among non-realtime work classes is determined by 
the scheduler mode in effect at the time. If the scheduler is in deadline mode, the 
scheduler attempts to meet the specified response times for each work class. Generally, 
work classes with lower values of resp are given priority for eligibility (memory) over 
those with higher values. Processes in work classes with higher values of quantum 
remain in memory longer than those with lower values. 

If the scheduler is in percent mode, the CPU time available for use (i.e., not used by 
realtime work classes and not idle) is distributed among the non-realtime work classes 
on the basis of their assigned values of percent. For example, if two work classes 
each have values of 20 for percent, they will get approximately the same amount of 
CPU time in any interval where both have sufficient demand. If one work class has a 
value of 10 for percent, and another work class has a value of 20, then the first will 
get approximately half the amount of CPU time as the second. Again, it is assumed 
that there is sufficient demand for this to be possible. 

By using the max_percent change code, the system administrator can limit a work class 
to a specified percentage of system resources. This control mechanism is effective only 
for non-realtime work classes, and only when the scheduler is operating in percent 
mode. If, for example, a work class is assigned a max_percent of 10, then it is 
limited to 10-percent of the total CPU time on the system in any interval of time. 
To enforce this restriction, the system will go idle, if necessary, rather than allow a 
work class to consume more than its max_percent of total CPU time. In practice, it 
may be useful to assign non-zero values of max_percent to some work classes, while 
assigning a value of zero (no limit) to others. In such a case, the scheduler will limit 
the resources of the first set of work classes to the percentages specified. It will then 
divide the remaining resources among the work classes with no limit, in proportion 
according to their values of percent. 
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NOTES ON LOAD CONTROL EQUATIONS AND GROUP PARAMETERS 
The load control equations are: 

max_prim = minu + (num/denom) "System_maxu 
absolute_max = minamax + (numl/denoml) i^system__maxu 

The max_prim equation for a group determines the maximum number of users in the 
group that may be logged in as primary users. Additional users from the group may 
be logged in as secondary users (subject to preemption) if the system is not full and 
the group's absolute_max figure is not exceeded. The absolute_max equation determines 
the absolute maximum number of users from the group (both primary and secondary) 
that may be logged in. This limit is not exceeded, even if the system is not full. 
Setting the value "3276.7" for the minamax parameter of a group indicates that no 
absolute_max limit is to be imposed on the group. 

The equations actually determine the maximum load units (rather than the maximum 
users) for the group. By default each user is given a load control weight of one unit, 
making the number of users from each group equal to the number of units. Weights 
other than 1 can be assigned (see the description of the SAT in the Multics System 
Administration Procedures manual. Order No. AK50 and the admin_util command in 
this manual). 

The system_maxu figure is the maximum units for the system (which is a function of 
shift and configuration), less the number of consoleless daemons and absentee jobs 
currently logged in. For example, if the maximum units is 80, but there are 7 
daemons and 3 absentee jobs in the system, the value of system„maxu used in the 
load control equations will be 70, not 80. 

The num, denom, numl and denoml variables in the load control equations are used 
to specify a percentage of the system_maxu figure. If the denom and denoml figures 

are set to the typical system system_maxu figures (70 in the above example, rather 
than 80), then the num and numl figures can be set to the desired number of users 
from the group (less the minu or minamax figure) that should be given primary status 
on a full configuration. If system_maxu falls below the full configuration value, the 
number of primary users allowed in each group gets reduced proportionally. 

Setting num or numl to zero disables the proportional load unit setting for the group, 
leaving the respective units figures as a constant, not dependent on system_maxu. 



2-203 



GB64-00 



ed_mgt 



ed_mgt 



EXAMPLES 

On a system with an 80~user capacity that normally runs 7 daemons and 3 absentee 
users, a group that should normally have 15 primary users, with a minimum of 3, set: 

minu =3 
num = 1 2 
denom = 70 

To limit this group to 30 users with a full configuration, but to no fewer than 15 
users on any configuration, set: 

minamax = 15 
numl = 15 
denoml = 70 

Since the system_maxu figure is a function of current load, as well as shift and 
configuration, the two equations are re-evaluated for each group, each time any user 
tries to log in. Thus, the max_prim and absolute_max figures are changing continually, 
and cannot be set or displayed by ed_mgt. There is one exception: the max_prim 
parameter for (only) one group may be set to "-1" to indicate "all the resL" The 
max_prim equation for that group is not evaluated, but rather, its max_prim figure is 
determined by deducting from system_maxu the max_prim figures computed for all 
other groups. 

The following list gives the keywords used in the ed_mgt change request to change the 
values of the variables in the load control equations: 



Variable 


Keywords 


max_pr im 


max_prim, maxp, maxu, m 


mi nu 


constant, const, con 


num 


num, numerator 


denom 


denom, den, denominator 


mi namax 


minamax, abs_max, abs 


numl 


numl 


denoml 


denoml, denl 



The variable shown as "minu" in the equation is the only one whose name is not one 
of the keywords accepted by the change request to change that variable. (Three 
variations on the word "constant" are used instead.) 

EXAMPLES OF WORK CLASS PARAMETER SETTING 

The following examples are present only to illustrate the use of ed_mgt, and the use 
of the load control group and work class mechanisms to achieve the objectives of 
management regarding the division of resources among users. They are not intended to 
be recommendations of specific ways of allocating those resources. This is especially 
true of the work class percentages used in the examples — the only meaning that may 
safely be attached to those numbers is that they must add up to no more than 100%. 
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The first example is based on the assumption that the MGT is in the state in which 
it is left when a new Multics site is initialized (3 groups, 1 work class). The others 
follow sequentially, with the assumption that the MGT is in the state in which it was 
left by the previous example. 

There are several places in the examples where a group of parameters is set to the 
same (usually null) value by one request, and then a subset of those is set to other 
(nonnull) values by subsequent requests. This takes advantage of the global-change and 
change-all-shifts features of the ed_mgt syntax, to minimize the amount of typing 
needed to accomplish a change. 

The ed_mgt prompting messages are omitted from the examples. 

It is recommended that the user work through these examples at a terminal, using a 
temporary copy of the MGT, and using the "p*" request to display the contents of 
the MGT at the end of each example. 

EXAMPLE 1 

The following simple set of group and work class definitions could be used to gain 
experience with the priority scheduler, before more complicated uses of it are 
attempted: 

Group Work_Class Exampl e_Percent 

System 1 15 
SysProg 2 15 
Other 3 70 

Assuming that the groups System, SysProg, and Other, and work class 1 (the defaults 
that are defined when a Multics system is first set up), and no others, are defined, 
and that shifts 1-4 (the defaults, as above) are in use, the following ed_mgt requests 
edit the MGT to define the above work class assignments: 

gc group wc i nt 0 

wc abs 0 . 
gc wc def i ned no . 
f 1 c defined shift 1-4 yes 

% shift 1-1* 15 

absentee shift \'k allowed . 
f 2 c defined shift 1-4 yes 

% shift l-i* 15 

absentee shift 1-4 allowed . 
f 3 c defined shift 1-4 yes 

% shift 1-4 70 

absentee shift 1-4 allowed . 
f System c wc int shift 1-4 1 
wc abs shift 1-4 1 . 
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f SysProg c wc int shift ]-h 2 

wc abs shift 1-^ 2 . 
f Other c wc int shift ]-h 3 
wc abs shift }--k 3 . 

The verify request may then be used to check for possible typing errors, and the pall 
request may be used to display the contents of the edited MGT. Neither of those 
requests should be used when the above editing is only partly done, since the MGT 
will be inconsistent (for example, the first three requests leave no work classes 
defined, and all groups in work class zero — an invalid state) and pall or verify 
would produce many error messages. 

EXAMPLE 2 

Add groups 10 and Backup; assign them to work classes 4 and 5 respectively. Define 
those work classes, assigning 5% to each. Take 10% from work class 1, which 
corresponds to group System (this group originally contained the SysDaemon and 
SysAdmin projects, but now has — practically — only SysAdmin, since the two most 
active daemons have been moved to separate work classes). 

a 10 1 0 

c wc int shift 1-4 4 

wc abs shift ]-k i* . 
a Backup 1 0 
c wc int shift ]-k 5 

wc abs shift }-k 5 • 
f it c defined shift ]-k yes 
% shift 1-4 5 

absentee shift ]-k allowed . 
f 5 c defined shift 1-4 yes 
% shift 1-4 5 

absentee shift 1-4 allowed . 
f 1 c % shift 1-4 5 . 

Then, using edit_proj, give the SysDaemon project the igroup attribute, and set its 
authorized groups to 10 and Backup. Edit the SysDaemon PMF, to give lO and 
Backup the igroup attribute, and assign them to groups 10 and Backup, respectively. 
Of course, the PMF must be compiled, and the PDT and SAT installed. The required 
order of installations is: MGT, SAT, then PDT. If the daemons are already logged in, 
they will remain in their old groups and work classes until the next time they are 
logged in (presumably at the next bootload). 

EXAMPLE 3 

To assign absentee jobs to work classes different from those of interactive users, take 
the following steps. 
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Clear all absentee allowed switches and zero all absentee work class assignments. Then 
define groups Absl and Abs2-4, for queues 1 and 2-4 respectively. Put queue 1 in 
work class 6 and give it 10%; put the others in work class 7, giving it 5%; take 15% 
away from the interactive users' work class. 

go wc absentee shift }-k not_allowed . 
gc group absentee no t_a1 lowed 

wc abs shift 1-4 0 . 
a Absl 3 0 

c wc int shift 1-4 6 
wc abs shift 1-4 6 
absentee a1 lowed 
absentee queue 1 . 
a Abs2-4 1 0 
c wc int shi f t 1-4 7 
wc abs shift 1-4 7 
absentee allowed 
absentee queue 2-4 . 
f 6 c defined shift 1-4 yes 
% shift 1-4 10 
absentee shift 1-4 allowed . 
f 7 c defined shift 1-4 yes 
% shift 1-4 5 

absentee shift 1-4 all owed . 
f 3 c % shift 1-4 55 . 



EXAMPLE 4 

This example shows how to assign work class percentages and memberships that vary 
with shift. 

There are likely to be more interactive users on the system during normal working 
hours (shift 1) than at other times. Therefore, decrease the interactive users' percent 
by 20% and increase that of absentee, on shifts 2-4. On shift 3 (midnight to 8 am), 
put all four absentee queues into one work class. 

f 3 c % shift 2-4 35 • 
f 6 c % shift 2-4 20 

% shift 3 35 . 
f 7 c % shift 2-4 15 

% shift 3 0 

defined shift 3 no . 
f Abs2-4 c wc int shift 3 6 
wc abs shift 3 6 . 
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Name: edit process audit flags 

SYNTAX AS A COMMAND 

ed i t__process_aud i t_f 1 ags {f 1 ags_str} 

FUNCTION 

turns on or off only those flags given in the flags^str. 

ARGUMENTS 

flags_str 

is an audit flags string acceptable to convert_access_audit_flags_. If you omit it, 
the command enters a prompt loop in which you are asked for an audit flags 
string. A entered alone on a line causes the loop to exit 

ACCESS REQUIRED 

You must have re access on system_privilege_ and access_audit_gate_ and r to 
>udd>SysAdmin>admin>sys_admin_data if you use the "default" keyword. 

NOTES 

For a description of the process audit flj^, see the new_user command and the 
section "Security Auditing" in the System Administration Procedures {AK50). 

This command is meant for experimentation with security audit control flags by the 
system security administrator. Permanent settings for processes should be placed in the 
appropriate PNT/SAT entries with the new_user and edit_proj commands. 

The special keywords "none", "all", and "default" are also recognized for the audit 
flags string. They specify 



"none" all audit flags turned off 
"all" all audit flags turned on 

"default" audit flags set to default found in sys_admi n__data. 
See also the display_process_audit_flags and set_process_audit_flags commands. 
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EXAMPLES 

edi t__process_audi t__f lags rcp=ma/ma,admi n=n/,special=/n 
di splay_process__audi t_f lags 

fsobj=N/R,fsattr=N/R,rcp=HA/MA,admin=N/R,special=R/N, . . . 

. . .other=N/R,admin_op,priv_op,faul tj'^smal l_cc,'^moderate_cc 

ed i t__process_aud i t_f 1 ags 

current flags: f sobj=N/R,f sattr=N/R, rcp=N/R,admin«R/R, . . . 
. . .sped a 1=R/R, other «N/R,admi n_op,pr iv__op, . . . 
... f aul t,^smal l_cc,'^moderate_cc 
enter flags: fsobj=r/ 

new flags: fsobj=R/R,fsattr=N/R,rcp=N/R,admin»=R/R, . . . 
. . .special=R/R,other=N/R,admin_op,pr lv_op, . . . 
. . .f aul t.'^smal l^cc'^oderate^cc 
enter flags: fsobj=/m 

new flags: f sobj=R/M, f sattr=N/R, rcp=N/R,admi n-R/R, . . . 
. . . spec ial=R/R,ot her =N/R,admin__op,priv__op, . . . 
... f aul t.'^smal l__cc,^moderate_cc 
enter flags: '^adml n_op,^f aul t,other«raa/ma 
new flags: fsobj=R/M,fsattr=N/R,rcp-N/R,admln*R/R, .. . 
. . .special=R/R,other=MA/MA,'^admi n__op,pr i v_op, . . . 
. . .'^f aul t.'^smal l_cc,'^oderate_cc 
enter flags: 



Name: edit__proj 

SYNTAX AS A COMMAND 

edit_proj Project_id {keyword {newvalue}} 

FUNCTION 

provides a single facility for the editing of all project data. You can invoke it in two 
ways. Either all data items that are part of project registration can be printed one at 
a time or a single data item can be changed. 
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ARGUMENTS 
Projeci_id 

is the Project.id of the project whose registration data items are to be edited. If 
this is the only argument you specified, edit_proj prints each data item one at a 
time and waits for a response from the accoimting administrator before 
proceeding. The accounting administrator can respond with any one of the 
following: 

carriage return 

to leave the item unchanged 

a new value 

to replace the printed value 

stop 

to exit immediately from the edit_proj command without making any changes 

keyword 

is the particular data item to be changed. Valid keywords are 



title 


t 


investigator 


! nv 


i nvest i gator_address 


1 nv__addr 


supervi sor 


sup 


supsrv i sor_address 


sup Suwr 


superv i sor__phone 


sup_phone 


account 


acct 


requisi tion 


req 


requ i s i t i on_amount 


amt 


cutof f_date 


cutoff 


b i 11 i ng_name 


bi llto 


bill! ng_address 


bi llat 


group 


grp 


attr ibutes 


attr 


grace 


gr 


administrator 


admi n 


quota 


q 


al ias 


aka 


groups 


gps 


m i n__r i ng 


mi n 


max__r i ng 


max 


max^foreground 


maxf g 


max_background 


maxbg 


abs_foreground_cpu_l imit 


absf gcpul im 


pd i r__quota 


pdq 


rate_structure 


rs 


account i ng_category 


acct^cat 
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newvalue 

is the new value of the data item identified by the specified keyword. When you 

give newvalue. give keyword. If you omit newvalue, edit_proj asks for it In 
both cases, the old value is printed. 

NOTES 

The meanings of the following parameters are explained in the Project Administrator's 
Manual (AK51), under the PMF description. 

group max_foreground 

attributes max_background 

grace abs_f oreground_cpu_rimi t 

m I n_r i ng pd i r__quota 

max_r i ng 

EXAMPLES 

To review all the registration data items of the States project and change the project's 
quota to 200, type: 

edit_proj States 



Title: 


Data Reduction for all States 


1 nvest i gator : 


Mr. M. Lee 


Address: 


Room 22 


Supervi sor : 


Ms. Hi Ikica Bjorn 


Address: 


Room 6 


Phone: 


555-1212 


Requisi tion: 


P033^^-J 


Amount: 


open 


Cutoff date: 


01/01/86 1935.1 


Bi 1 ling name: 


Fiscal Office 


Address: 


Room 8 


Rate structure: 


default 


Group: 


Other 
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Attributes: anonymous, preempting, brief, vinitproc, 

vhomedir, nostartup, v_outer_module 

Grace: 2880 

Project administrators. Type "." to delete. 
Administrator ID: Brelcke. States 

Administrator ID: 

Quota: 100 

200 
A1 i as: 

Do you wish to review? 
no 

r 19:39 2.661 197 

From I ni tial izer .SysDaemon.z (install) 1940.0: 
installed sat for SAl.SysAdmin 

Another way to accomplish the same quota change is to type: 
edit_proj States quota 200 

!f the accounting administrator requests a change tc either the requisition or account 
number of the project, he is asked a question to which he must respond with one of 
the following words: 

drop 

to cause the charges to the old account and requisition to be eliminated 
transfer 

to cause the charges to be transferred from the old account and requisition 
to the new account and requisition 

bill 

to cause the charges to be billed to the old account and requisition, and to 
cause the new account and requisition to start off with a clean slate. 

For example: 

edft_proj States req P05566-J 
What is the disposition of charges of 
$1233.79 to account 70906, req P033^'»-J? 

bi 1 1 

r 19:39 2.661 197 
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Name: edit_proj$change__all 

SYNTAX AS A COMMAND 

edi t_proj$change_,an keyword {ol devalue} {new_va1ue {-all}} {-long} 
FUNCTION 

changes project registration information for all projects registered on the system. (The 
accounting administrator can use the edit_proj conmiand to change the registration 
information for a single project) 

You can invoke this command in several ways, as described below: 

1. In the format "edit_proj$change_all keyword." in which case you are queried for 
a change to "keyword" for each project on the system. 

2. In the format "edit_proj$change_all keyword old_value," in which case you are 
queried for a change to "kejrword" for each project for which the value of 
"keyword" is "old_value." 

3. In the format "edit_proj$change__all keyword old_value new_value," in which case 
the "old_value" of keyword is set immediately (without a query) to "new_value." 

4. In the format "edit_proj$change_all keyword new_value -all," in which case you 
are queried to make sure you want to set the value of "keyword" to "new__value." 
If you respond "yes," the change is made immediately. 

ARGUMENTS 

keyword 

is the particular keyword whose value is to be changed. Valid keywords are 

title t 
Investigator inv 
i nvet i gator_address i nv_addr 

sup 

sup_addr 
sup_phone 
acct 
req 
amt 

cutoff 
billto 
billat 
grp 



supervisor 

supervi sor_address 

superv i sor_phone 

account 

requi si tion 

requ i s i t i on^amount 

v«vi II \ja 

bill! ng_name 
bill ing_address 
group 
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attr ibutes 


attr 


grace 


gr 


admi ni strator 


admi n 


quota 


q 


d i r__quota 


dq 


a1 i as 


aka 


groups 


grps 


m i n_r i ng 


mi n 


max_r 1 ng 


max 


max_foreground 


maxf g 


max_background 


maxbg 


abs_f oreground__cpu_1 imi t 


absfgcpul im 


pd i r__quota 


pdq 


rate__structure 


rs 


account i ng_category 


acct_cat 


author i zat ion 


author i zat i on 


audi t 


aud i t 



old_value 

is the current value associated with keyword. This argument cannot be specified 
unless the keyword argument is also specified. 

new_value 

is the new value to be associated with keyword. This argument cannot be 
specified unless (1) the keyword argument and the old_value argument are both 
specified, or (2) the keyword argument and the -all control argument are both 
specified. 

CONTROL ARGUMENTS 

-all 

specifies that all the specified project keywords are to be immediately changed 
after a single query. This control argument can be used only as described in 
format 4, above. 

-long 

specifies that the system issue a message when a change becomes effective. 
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EXAMPLES 

to specify that the system query for a new value for the title of all projects on the 
system, type: 

edi t__proj$change__all title 

To specify that the system query for a new value of dir_quota for all projects in 
which the current value of dir_quota is 10, type: 

ed i t_proj$change_al 1 dir__quota 10 

To specify that the system change the value of dir_quota for all projects to 10 after 
a single query, type: 

edi t_proj$change_an dir__quota 10 -all 

To specify that a new dir_quota value of 100 be specified for all projects whose 
current dir_quota value is 10 and that the change is to take place without a system 
query, type: 

ed i t_proj $change_a 1 1 dlr_quota 10 100. 



SYNTAX AS A COMMAND 
et path {-control_args} 
FUNCTION 

sets up and tests EIS instructions in a controlled environment. You must prepare an 
input script describing the EIS instructions to be tested. From this input script the 
EIS tester builds the EIS instructions (one at a time) and the indirect words, 
descriptors, and data that each instruction needs. The instruction to be tested is set up 
in a special ALM segment (etx). The eis_tester command calls etx in order to execute 
the EIS instruction; etx returns to eis_tester when the instruction has been executed. 
After executing the instruction, eis_tester tests correct execution of the instruction. If 
one of the test scripts in the eis_tester data base fails and the successful execution of 
that test is dependent upon installation of a particular FCO, the FCO number is 
displayed in the error message. 



Name: eis tester, et 
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ARGUMENTS 
path 

is the pathname of a segment that contains input script data that defines the 
instructions to test 

CONTROL ARGUMENTS 

^ -brief, -bf 

suppresses all output except identification and error messages. 

-nox 

sets up the instruction but does not execute it; used to test the validity of the 
input script. 

-debug 

runs the test in a debugging loop where each instruction is tested 10 times but 
results from the test are not checked. Each time through the loop the instruction 
is set up completely, including all the specified faults. 

-select N, -sel N, -do N 

process^ only test N (where N is a positive decimal number). This number has 
no relationship to the -ns field in any test. 

-help 

displays a brief usage statement 

-instruction_type INSTR, -inst INSTR 

processes only tests that contain the instruction INSTR. 

-long, -Ig 

displays all the related test information prior to executing a test. 

-repeat N, -rpt N 

repeats the entire execution of the selected tests N times. 

-stop_on_failure, -sof 

displays the failing data, machine condition, and history register information and 
return to command level if an error is detected in a tesL The default is to 
display the failing data and continue with the next test 

-from N, -fm N 

starts processing test N (where N is a positive decimal number) and continues 
processing all remaining tests in the input segment unless -to is used. 

-to N 

stops processing after test N (where N is a positive decimal number). If -from is 
not u^, tests one through N are processed. 
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NOTES 

Before eis_tester calls etx to execute the instruction, it sets up some special padding 
around the data field that is modified by the EIS instruction. Eight special characters 
(octal 717) are put in front of and at the end of the result data string. The result 

area itself is initialized to all zero bits. 

When called to execute the EIS instruction, etx does the following: 

1. Saves the current pointers and registers. 

2. Loads the pointers and registers from values set up by eis_tester. These are the 
values of the pointers and registers when the EIS instruction is actually being 
executed. 

3. Sets indicators to preinstruction test values. 

a. All indicators except b and c below are off. 

b. The BAR MODE indicator is always on. 

c. If the test instruction is expected to turn on any of the three overflow 
indicators (ov, eo, eu), then the om (overflow mask) indicator is turned on so 
an overflow fault is not taken. 

4. Transfers to the instruction area in etx itself where eis_tester has set up the EIS 
instruction and its descriptors. 

5. After the EIS instruction has been executed, etx stores the values of the 
indicators, pointers, and registers so that eis_tester can examine them. 

6. Reloads the pointers and registers that were saved by etx. 

7. Returns to eis_tester. 

After the execution of the EIS instruction, eis_ tester makes the following tests: 

1. Checks to see that the data resulting from the instruction is correct. 

2. Checks to see that the indicators are set correctly. 

3. Checks to see that a truncation fault was correctly taken or not taken. 
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INSTRUCTION AREA 

The EIS instruction is set up in a special area in etx. This area consists of seven 
words. The first three words of the instruction area are set up in the last three 
words of a page. The last four words of the instruction area are the first four words 
of the next page. By positioning the instruction in the instruction area, you can 
position the instruction on a page boundary. Those words in the instruction area that 
are not used for the EIS instruction itself are set up as nop instructions. The default 
position of the instruction word is in instruction area word 4. This places the 
instruction at word 0 of a page. 

PAGE A WORD 1 



DATA AREAS 

The data referenced by each descriptor of the instruction is set up in a special data 
area. There is one data area used for every descriptor of the instruction. Each data 
area consists of three pages. The default starting position of the data is character 0 
of word 0 of page 2. The last 32 words of page 1 and the first 32 words of page 3 
can also be used to hold the test data. Thus the maximum data size of any string is 
1088 words or 4352 (9-bit) characters. You can position the start of the data string so 
that it starts in page 1. Thus you can define data strings that cross page boundaries. 
A long data string can cross two page boundaries. 

Depending on what modification is used by the instruction, the data areas used may 
or may not be in the same segment 

If a descriptor is referenced via an indirect word, then the descriptor is set up in a 
special page of its own. Depending upon the modification used in the indirect word, 
the descriptors may be in different segments. 

PAGE FAULTS 

You have control over a maximum of 13 page faults during the testing of any EIS 
instruction. These 13 pages have consistent meaning to eis_tester, even thou^ for 
different tests they may actually be physically different pages in different segments. 



WORD 2 
WORD 3 



PAGE B 



WORD k 
WORD 5 
WORD 6 
WORD 7 



< — Default position of 
instruction word. 
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The 13 pages are: 



1. 


Page 


1 of the instruction area 


I. 


Page 


2 of the instruction area 


3. 


Page 


containing indirect descriptor 1 


4. 


Page 


1 of data area 1 


5. 


Page 


2 of data area 1 


6. 


Page 


3 of data area 1 


7, 


Page 


containing indirect descriptor 2 


8. 


Page 


1 of data area 2 


9. 


Page 


2 of data area 2 


10. 


Page 


3 of data area 2 


11. 


Page 


containing indirect descriptor 3 


12. 


Page 


1 of data area 3 


13. 


Page 


2 of data area 3 


REGISTER ASSIGNMENT 



You can control the type of modification used by each EIS instruction tested. 
However, for each type of modification (depending upon the descriptor number), 
eis_tester assigns the register to be used. The specific use of pointers and registers is 
not under your control when using the eis_tester script input method. 

Pointer registers not used during the instruction are set to null (77777 ] 1). Index 
registers and the A and Q registers that are not used are set to 8191 decimal (17777 
octal). 

AR modification involves the use of a pointer register. Both descriptors and indirect 
words can use AR modification. A general rule followed by eis_tester is that AR 
modification implies the data referenced is in an external segment. The pointer 
registers used by eis_tester for the EIS instruction are: 

AR modification in a descriptor 

descriptor 1 prl 
descriptor 2 pr2 
descriptor 3 prB 



AR modification in an indirect word 

descriptor 1 prh 
descriptor 2 pr5 
descriptor 3 pf? 

pr6 is used to point to your current stack frame and must be preserved in a valid 
state in order for any conditions to be signaled correctly. 
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SEGMENTS USED BY EISJESTER TO EXECUTE AN INSTRUCTION 

Index register modification can be specified for descriptors and for indirect words. 
The effective offsets used for index modification are always set up by eis_tester in 
terms of words. For some descriptors, the value in the index register must be in units 
of characters. The character size also varies with the value of the ta field of the 
descriptor. The index registers assigned by eis_tester and the effective word offset 
they contain are given below. 

Index register modification of a descriptor 

descriptor 1 XI 1 word 

descriptor 2 X2 2 words 
descriptor 3 X3 3 words 

Index register modification of an indirect word 

descriptor 1 X4 4 words 

descriptor 2 X5 5 words 
descriptor 3 X7 7 words 

RL modification can be specified for the descriptors of certain instructions. The value 
put in the register is specified by you. The register assigned is controlled by 
eis_tester. The following registers are used: 

descriptor 1 A 
descriptor 2 Q 
descr i ptor 3 X6 

The execution of an instruction by eis_tester can involve up to seven segments: 

etx et i 1 etdl 
etll etd2 
eti3 etd3 

The notation etiX means etil, eti2, or etiS, depending on which of the up-to-three 
descriptors or operands is of current interest Similarly, etdX means etdl, etd2, or 
etdS. 

The first list below states the possible segments in which various items can be located, 
while the second list states what segment a descriptor or an operand is in under 
various conditions. 
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ITEM 

Instruction word 

Indirect word pointing to descriptor 

Descr i ptor 

Operand 



etx 

X 
X 
X 
X 



SEGMENTS 
etiX 



etdX 



Is AR Used 
to Access 
Descr i ptor? 

No 
No 
Yes 
Yes 



Is AR Used 
to Access 
Operand? 

No 
Yes 
No 
Yes 



Descr i ptor 
Locat i on 

etx 
etx 
etiX 
etiX 



Operand 
Location 

etx 
etdX 
etiX 
etdX 



EISJESTER PRINTOUT 

The eis_tester program prints a message noting the beginning of each instruction test. 
It also prints the number of this test. If there were errors, it prints the incorrect 
data or incorrect indicators. 



If you do not specify -bf (see "Usage" above), then the data that eis_tester has set 
up for this instruction is printed before the instruction is executed. The following 
notes describe this printout: 



1. Pointers enclosed in parentheses point to where the data is set up in the eis_tester 
segments. 

2. If none of the pointer registers are used by the instruction, then none are 
printed. The same is true of the registers. 

3. The names of the pages that take faults cannot be the names of all the pages 
specified in a page statement. See the last two complete examples at the end of 
this description for clarification. 

4. If the first word of a data string does not begin at character 0 of a word, or if 
the string does not use all four characters of the last word, then the imused 
characters of the first and last words of the string are printed as blank 
characters. 



5. The test string is not printed from one of the areas used by the instruction but 
rather from one of the buffers used by eis_tester. 
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6. The test and result strings are both padded by eis_tester with special characters. 
These special characters are not printed out in octal like the rest of the string; 
instead, each of these special characters is printed as three x's (xxx). 

HO\N TO CALL EIS JESTER 

The eis_tester program is the main procedure in the EIS instruction tester. It calls 
et_test to parse the statements in your data file. It translates these statements into the 
data needed to build and test an EIS instruction in the external segment etx. After 
building the instruction, this procedure calls etx in order to execute the EIS 
instruction. When etx returns, the results of the EIS instruction are examined. The 
eis_tester program continues to build and test EIS instructions until there is no data 
left in the input file. The failure of one instruction only causes the termination of 
that one instruction test Any remaining instructions specified in the input file are 
processed and tested. 

HOW TO WRITE SCRIPT INPUT TESTS 

The script input test consists of a series of eis_tester statements. The first statement 
in any test must be an inst statement. This statement signifies the beginning of one 
test. 

An input script segment can contain several tests. All statements from the beginning 
of the inst statement to the beginning of the next inst statement (or, if none is 
found, to the end of the segment) are considered part of the same tesL 

The format of a statement is- as follows: 

name requi red__f ield {-control_args} ; 

where: 

name 

is the four-character statement name. There are four types of eis_tester 
statements: 

inst 

defines the instruction word and many control variables. 

desc 

defines a descriptor. 

data 

defines the data associated with a descriptor. 

page 

defines the page faults taken by the instruction. 
These statements are discussed in detail below. 
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required_field 

is required information used by all but the page statement. 
control_args 

are optional control arguments, explained in the individual statement descriptions. 
SYNTAX AND METALANGUAGE 

All statements must end with a semicolon (;). There can be any number of blanks, 
tabs, and newline characters between any fields in the statement, including before the 
name field. Wherever blanks are permitted, there can also be comment fields. A 
comment field begins with a /* character pair and ends with the next */ character 
pair. 

In this description, lowercase letters are used to indicate characters that are to be 
typed in for input to eis_tester. Uppercase letters are to be replaced with the desired 
character before the script is typed. 

INST STATEMENT 

The inst statement defines the beginning of an eis_tester test. It is used to define all 
of the fields in the instruction word of the EIS instruction. It is also used to set up 
the following special control arguments: 

L Instruct eis_tester to execute this instruction several times. 

2. Position the instruction within the instruction area. 

3. Define an identifying string that is printed with the test. 
An inst statement has the following format: 

inst opcode_mnemoni c {-contro1__args} ; 

where: 
inst 

is the four-character statement name. 

opcode_mnemonic 

is the mnemonic name of a storage type EIS instruction. 

CONTROL ARGUMENTS 

are optional and can be chosen from the following: 
-tbA 

turns on the truncation bit. The A is either y or n to signify whether or not the 
instruction is to take a truncation fault (y = yes, n = no). The default is n. 
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-fb 

turns on the fill bit The default is off. 

-pb 

turns on the plus sign bit. The default is off. 

-rb 

turns on the rounding bit. The default is off. 
-fcA 

defines the fill character to be the character specified by A. (No space between c 
and A and no quotes are permitted.) 

-mcA 

defines the mask character to be the character specified by A. (No space between 
c and A and no quotes are permitted.) 

-In N 

defines the loop number as X. This is the number of times this instruction test 
is performed. The default is 1. The maximum value of X is 4. 

-io N 

defines the instruction offset. It is used to position the instruction relative to a 
page boundary. The default is 0. This places the instruction at word 0 of the 
second page of the instruction area. X indicates the number of words of the 
instruction to be placed in the first page of the instruction area. The maximum 
value of X is 3= 

-nt "A...A" 

defines a note. It can be used to identify each tesL The term consists of a 
character string between quotes. Up to 32 characters can be used. No embedded 
quotes are allowed. 

-bo AAA 

defines a Boolean operator. AAA is the name of the operator. The names 
eis_tester has assigned to the Boolean operators are given below. Next to these 
names are the actual BOLR codes they represent 

zer 0000 

and 0001 

axr 0010 

mov 00 1 1 
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xra 0100 

ra2 0101 

xor 0110 

orB 0111 Type in orB, where B is a space 

nor 1000 

nox 1001 

iv2 1010 

xrx 1011 

inv 1100 

xxr 1101 

nan 1110 

set nil 



-ir {terms} 

is a multifield control argument that defines the correct state of the indicator 
registers after the EIS instruction has been executed. An -ir control argument can 
be followed by any number of specific terms. These terms can be in any order 
and can be separated by any number of skip fields. Each term is a two-character 
identifier of an indicator register biL 

A control argument of "-ir zr" means that the zero indicator is expected to be 
on at the end of the EIS instruction. Valid indicator register term values are: 

2r zero 

ng negative 

cr carry 

ov overflow 

eo exponent overflow 

eu exponent underflow 

om overflow mask 

tr tal 1 y runout 

pe par i ty error 

pm par i ty mask 

bm BAR mode (always turned on by eis_tester) 

tn truncation 

mw multiword instruction interrupt fault 

ab absolute mode 

If the script turns on eo, eu, or ov, then eis_tester automatically turns on the 

overflow mask bit in the expected indicator's result. 
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-mfX {terms! 

is a multifield control argument that defines one mf field of the instruction. 
Some instructions do not have mf fields in the instruction word for all of their 
descriptors. The -mfX control argument is then used to specify any ar or reg 
modification in the descriptor itself. An example is the mvt instruction. X 
denotes which mf field is being defined. It must be from 1 to 3 and is 
associated with descriptor X. This descriptor number can be followed by up to 
four terms. All four terms are optional and can be specified in any order. The 
valid terms are: 

ar 

rl L 

idA 

reg 



THE AR TERM 

The ar term specifies that, for this descriptor, the address register modification is be 
used to access the operand. In Multics, it is called pointer register modification. The 
pointer assigned is prX. When this term is specified, the data referenced by this 
descriptor is placed in the segment etdX. 

THE RL L TERM 

The rl L term specifies that, for this descriptor, the register length modification is be 
used. This term must be followed by a decimal number L, which specifies the 
character length of the data. The character size is defined within a desc statement 
(for 4-, 6-, or 9-bit characters) or inferred from the instruction mnemonic (for bit 
strings). This value is placed in the selected register, and the N field of descriptor X 
contains the register modification tag code. The registers assigned are: 

X = 1 - A 

X = 2 - Q 
X = 3 - x6 



THE IDA TERM 

The idA term specifies that descriptor X is to be referenced via an indirect word in 
the instruction. In the idA term, the A denotes what modification is to be used in 
the indirect word: a for address register, r for register, or b for both. 

If no A character is given in the idA term, then there is no A modification in the 
indirect word. 

ida 

specifies that address register modification is to be used to access the descriptor. 
When this is specified, the descriptor is placed in the segment etiX. 
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The pointer registers assigned to the indirect word are 

indirect word 1 => prk 

indirect word 2 => pr5 

indirect word 3 -> pr? 



idr 

specifies that register modification is to be lised to access the descriptor. The 
indirect word is modified by index register 4, 5, or 7. NOTE: This modification 
is in terms of words. 

idb 

specifies both a and r modification as described above. 
THE REG TERM 

The reg term specifies that descriptor X is to be modified by an index register. The 
value in the index register is a character offset and is (X*4). The index register 
assigned is index register X. The value placed in index register X is dependent upon 
the type of instruction and the appropriate character size. It is in the following units: 

WORDS 



BITS 

for all bit string instructions 



CHARS 

for all others. The actual units depend upon the character size. The default is a 
9-bit character size. 
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If it is necessary to write a script in wliich the placement of the instruction, indirect 
words, descriptors, and operands in specific segments is important, the following list is 
helpful. 



Script Elements Used 
in-mfX Fields 



id 



id 



i da 



idr 



i da 



idr 



ar 
ar 
ar 
ar 

i db ar 



idb 



Descr i ptor 
Locat i on 



etx 
etx 

etx 



etx 
etx 



etiX 
etiX 

etiX 
etiX 



Operand 
Location 



etdX 
etdX 
etdX 
etdX 
etdX 



etx 



etx 



etiX 



etiX 



EXAMPLES OF INST STATEMENTS 
/* Exampl e 1 . ''/ 

inst mlr -nt "Example 1 " 

-fc* Comments can go anywhere except inside a term 

-fb 

-mf2 /* Note order is not important. «/ 
rl 3 id ar reg 

-mfl ar idb reg rl 3 ; Statement must end with ";" */ 



/* Example 2. */ inst cmpc /* mnemonic name must 

" be first term. «/ 

-mfl ar 

-nt " example 2" -mf2 rl 3 

-fc /* Use escape to enter octal character */ 

-ir cr zr ; /« indicator bm i s on by default. «/ 
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/" Example 3. */ 



i nst 
-mc9 
-In 3 
-io 2 



scm 



-nt "scm examp. 



/" Make this test 3 times. 

/" Put instruction word and first descriptor 

* in page 1 of instruction area. */ 



-mf 1 
-mf 2 



reg ar 
ida; 



Example k. */ 



i nst 



ad3d 



-mf3 ar -mf2 reg -mfl idr /* -mfx items can be in any order *»/ 
-rb -pb; 



/* Example 5* "/ 

inst csr -fb -bo and -mf 2 rl 36; 



DESC STATEMENT 

The desc statements are used to specify certain fields in the descriptors. Each desc 
statement deals with only one descriptor. The fields in a descriptor not specifically set 
up by a desc or an inst statement are set to zero. If zero bits in all of the fields 
are needed, then no desc statement need be specified for that descriptor. 

The -cp, -bp, and -cn fields of a desc statement interact with the -do field of the 
associated data statement. See the complete examples at the end of the eis_tester 
description for illustrations of the interactions. 

In general, the order of the desc statements is not important, and the can be mixed 
in with any other statements. However, if the instruction is CMPC, SCD, SCDR, 
SCM, or SCMR, then the desc 2 statement cannot specify a -ta field. Descriptor 2 
must use the value specified in descriptor 1. To use this feature, the desc 1 statement 
must precede the desc 2 statement. 

A desc statement has the following format: 
desc num {-control__args} ; 
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where: 
desc 

is the four-character statement name. 

num 

is the number of the descriptor. It must be 1, 2, or 3. 
CONTROL ARGUMENTS 
can be chosen from the following: 
-cp N 

is used in bit string instructions to specify a (9-bit) character offset when 
developing an operand address where N must be a number from 0 to 3. 

-bp N 

is used in bit string instructions to specify a bit offset within a 9-bit character 
when developing an operand address where N must be a number from 0 to 8. 

-cn N 

is used in character string instructions to specify a character offset when 
developing an operand address where N must be a number from 0 to 7. The 
quantity of bits associated with each character (4, 6, or 9 bits) is specified by the 
N argument supplied with the -ta or -tn control argument. 

-ta N 

defines the alphanumeric character type where N must be 9, 6, or 4. The default 
value is 9. 

-tn N 

defines the type of numeric character where N must be either 9 or 4. The 
default value is 9. 

-sd STR 

is the sign and decimal type. The STR argument must be one of the following 
characters: 

f - Floating point, leading sign 

1 - Leading sign, scaled 

t - Trailing sign, scaled 

n - No sign, scaled 
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-sf N 

is the scaling factor where N is a signed (or unsigned) decimal number, 
-ns N 

is the number of characters or bits in a string where N is an unsigned decimal 
number. There is no default value. 

-nn N 

is the number of characters in a numeric string where N is an unsigned decimal 
number that must not be greater than 64. There is no default value. 

EXAMPLES OF DESC STATEMENTS 



/* Example 1. J^/ 

desc 1 -ns 8 -ta 6 -cn 5; 



/'v Example 2. 

desc 3 ~cp 2 

-bp /* Comments can come between control argument names 

5t and the term. *•/ 5; 
/" No -ns control argument. This is valid if -mf3 

control argument in Inst statement 
* specified rl term. '"V 



/* Example 3. */ 

desc 2 

-tn k -cn 3 ~sd n /* No sign. */ 
-sf -100 -nn 12; 
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DATA STATEMENT 

The data statements are used to describe the data that a descriptor references. Every 
test requires at least as many data statements as there are descriptors for the EIS 
instruction being tested. 

The eis_tester program can determine which descriptor references the result data. The 
data entered for this descriptor is not set up in the data area referenced by the 
descriptor. Instead, this data area is initialized to all zero bits. The input data is 
saved and used to test the result of the instruction. Some special notes about data 
statements are given below: 

1. For those instructions that both read and write data into the same string (e.g., 
ad2d, sb2d), you must enter a data 3 statement that describes the resulting data 
referenced by descriptor 2. The data input via the data 2 statement is the data 
initially referenced by descriptor 2. 

2. The data pointer for each descriptor is set by default to character 0 of word 0 
of page 2 of the data area for that descriptor. You can adjust this data pointer 
by certain (9-bit) character offsets. 

3. The input string defined by you is placed in the data area starting at the first 
character referenced by the effective data pointer. It is important to remember 
this. If the descriptor associated with this data area specifies that the first 
character of the string is not character 0 of the first word, then the missing data 
must be reserved when the input string is specified. 

4. The -do field of a data statement interacts with the -cp, -bp, and -cn fields of 
the associated desc statement. See the complete examples at the end of the 
eis_tester description for illustrations of the interactions. 

A data statement has the following format: 
data num {-control_arg} data_fields; 
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where: 
data 

is the four-character statement name. 

num 

is the number of the data field. It must be either 1, 2, or 3. In some cases, a 
data 3 statement is valid even when there is no third descriptor. In this case, it 
is used to input test data. See the last complete example (csl instruction) at the 
end of this description. If the descriptor that points to this data does not use 
address register or register modification, then only offsets that are a multiple of 4 
are accepted. The data used by EIS instructions is always string type data, and 
thus the input modes are limited to the two described below. 

CONTROL ARGUMENTS 

-do X 

where X must be a decimal integer from -128 to +4096 that represents a 9-bit 
character offset from character 0 of the middle page of the data area. 

DATAJIELDS 

are the following types. They can be intermixed. The maximum size of the data is 
1088 words (4352 characters). 

ASCII 

is an ASCII string. It must be enclosed in quotes. The maximum size of any one 
field is 256 characters. Quote characters can be entered in the string by 
expressing them as double quotes ("")• 

OCTAL 

is a string of octal digits. The first nonoctal-digit-type character found indicates 
the end of a string of octal data. The converted octal string is padded on the 
right with zero bits to make it an integral number of 9-bit characters. For 
example, data 123 45 6 7777; becomes 123 450 600 777700. 

The repetition factor (XX), an unsigned decimal number enclosed in parentheses, 
can be used to specify the repetition of a field. Only the data field immediately 
following the repetition field is repeated. 
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EXAMPLES OF DATA STATEMENTS 

/* Example 1. four characters of data starting at the 

* beginning of the default data area. */ 

data 3 "abed"; 

Example 2. Moves the same data field back two 

* characters. This splits the string across a page. 

* NOTE: The input string is the same even though it is 
entered differently. «/ 

data 2 -do -2 "ab" "cd"; 

/* Example 3« The same as example 2 only it specifies 

* some of the data in octal. 

data 1 "ab" U31^^ "do -2; 

/" Example k. A string of: 

^■^ "12121212121212121212", that is 10 "12" strings. */ 



data 2 "12" 06l062 "1" "2 
061 062 
(3) "12" 
(3) 061062; 



/•< Example 5' The effective data address to be 

* word 1 of page 2 of the data area. However, the cn 

iieiG Oi Lne GeSCi:pL«^! Sp/Suiiics wsiai. Liic !!;=>;. 

* character of the word that is used is character 
3« Put some fill characters in the first 

* three characters. 

*/ 

data 2 -do h /-h Fill characters. Not 

* referenced by the instruction. */ 
"abed" ; /'t The actual data string with which 

" the instruction works. >'«/ 
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PAGE STATEMENT 

The page statement is used to control page faults during the execution of the EIS 
instruction. The default case is that no page faults occur. The eis_tester program 
requires that you specify those pages on which faults are to be taken. 

If you specify a page that is not actually used by the instruction (for example, the 
third page of a data area that has a one-character string), there is no harm. There is 
also no page fault. 

All the pages used by an EIS instruction have been assigned names. For pages other 
than the two instruction area pages, the names can reference physically different pages. 
Their use by the EIS instruction is always the same. 

The format of a page statement is: 

page {-control_args} ; 



ARGUMENTS 
page 

is the four-character statement name. 
CONTROL ARGUMENTS 

specify what pages are to have page faults and be chosen from the following: 
-inl -in2 

the two pages of the EIS instruction itself take a page fault, 
-idl -id2 -id3 

the pages used by descriptors referenced via indirect words take a page fault, 
-dll -dl2 -dl3 

the three pages of data referenced by descriptor 1 take a page fault. 
-d21 -d22 -d23 

the three pages of data referenced by descriptor 2 take a page faulL 
-dSl -d32 

the two pages of data referenced by descriptor 3 take a page fault. 

-all 

specifies that all of the pages defined for this instruction take a page fault. If 
other control arguments are entered along with the -all control argument, then the 
pages specified do not have page faults. 
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RUNNING EISJESTER WITH OTHER USERS 

If eis_tester is to be run while other users are on the system, it is not possible to 
positively guarantee that selected pages will not take a page fault. The "page -all;" 
statement causes eis_tester to flush all the pages of the etx, etil, eti2, eti3, etdl, etd2, 
and etdS segments out of main memory. Using "page -all -in2;" results in flushing all 
pages, touching page in2, and transferring control to etx. The touching of page in2 
brings it into main memory. However, the overall system activity may be such that 
eis_tester loses control before reaching page in2, eis_tester and etx being displaced by 
pages for other users, control being returned to etx, execution continuing, and page in2 
being no longer in memory. Then, when page in2 is needed, a page fault occurs. 
Therefore, a general guideline is: if eis_tester is run when other users are on the 
system, use the "page -all;" statement. 

However, if eis_tester is to be run as the only user (nondaemon) process on the 
system and the "page" statement is not used, the pages should be in main memory 
when wanted. Some hardware problems may require running tests with and without 
page faults to isolate the problem. You should be aware that just because eis_tester 
attempts to avoid a page fault and the eis_tester output does not state that a page 
fault will occur does not necessarily mean that a page fault will not occur. 

EXAMPLES OF PAGE STATEMENTS 



/* Example 1. »»/ 

page -in2 -id3 -cl32 
-dl2 -dl2 -dll -idl; 



/* Example 2. 

page -all; 



/* Example 3« Take faults on ALL pages EXCEPT 

* pages in2 and id3 ''/ 

page -in2 -all "id3; /* Notice order is not 

* important. >''/ 
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EXAMPLES OF ACTUAL TEST SCRIPTS AND THEIR OUTPUT 



/'« mIrlO * * This test is the same as the test mlr3 except that * the 
descriptors use AR, REG, and RL modification " and use indirect 
descriptors. The indirect « words use both REG and AR modification. «/ 

inst mlr -nt "10." -io 1 -mf 1 rl 20 

ar /" This puts the data in etdl. */ 
reg />'« Use index register 1.. */ 

idb /* This adds indirect descriptors. Descriptors 
" go in segments etil and eti2. «/ 

-mf2 idb 

rl 20 

reg 

ar; 

desc 1 -cn 2; 
desc 2 -cn 2; 

data 1 -do -20 " " (5) "abed" ; 

data 2 -do -20 000 000 (5) "abed" ; /jV Fill for -cn 2 

* must be zeros. '</ 

page -inl -in2 -d22 -d21 -dll -dl2 -idl -id2 -id3 -d32; 
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et mlrlO -nox 

/'«The absence of any output from the 

*et mlrlO -nox input line means that the 

"Script passes the validity checks that eis_tester performs. 

*/ 
et 

TEST 1 (mlr) 



EIS instruction: ( 262|3777 ) I nd Desc. 
000172100571 



4000340001 u -> 100007200005 ( 327 

500043000115 -> 200016200006 ( 330 



100 ) 
100 ) 



Pointer Registers; ( 262|20 ) 

pro - pr3 7777771 1 332|1763 333|1753 777777|1 
pr4 - pr7 327^0 330|30 777777|1 777777|1 

Index Registers: ( 262 | 70 ) 

XO - X7 17777 h 10 777 4 5 17777 17777 
A 000000000024 Q 000000000024 

Test Indicators: ( 262 | 1 11 ) 
000000000200 

This test takes 8 page faults. 

inl in2 idl dll dl2 id2 d21 d22 

data field 1 ( 332 | 1773 ) 

000000141142 143144141142 143144141142 I43l44l4ll42 
143144141142 143144 

data field 2 ( 333|1773 ) 

Result data field initialized to all zero bits. 

test data { 262 1 15776 ) 

xxxxxxxxxxxx xxxxxxxxxxxx 040040l4ll42 I43l44l4ll42 
143144141142 143144141142 143144141142 I43l44xxxxxx 
xxxxxxxxxxxx xxxxxx 

/" Test mvt instruction. */ 

inst mvt -nt "3" -fc /* Char is octal 1. */ -mfl rl 3 ar reg idr -mf2 
ar reg ida -mf3 reg ar; 
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desc 2 -ns 8; 

data 1 -do -2 003 002 001; 
data 2 -do -6 "321111" "11"; 
data 3 -do -1 "0" "123"; 

page -all - i n2; 

et 

TEST 1 (mvt) 

EIS instruction: ( 262|i+000 ) I nd Desc. 
001132160571 

05177^000011+ -> 100007000005 ( 262 
500050000100 -> 200016000010 ( 330 
300025000113 



52000 ) 
100 ) 



Pointer Registers: ( 262 | 20 ) 



pro - pr3 777777 
prh - pr7 777777 



1 332 
1 330 



1767(18) 333|1756 (18) 33^|17^7(27) 
30 777777 1 1 771177 \^ 



Index Registers: ( 262|70 ) 

XO -X7 17777 ^ 10 777 ^ 5 17777 17777 
A 000000000003 Q 000000017777 

Test Indicators: ( 262 | 1 1 1 ) 
000000000200 

This test takes 11 page faults. 

id! d11 d12 dl3 id2 d21 d22 d23 d31 d32 d33 

data field 1 ( 332|1777(l8) ) 
003002 001 

data field 2 ( 333|1776(l8) ) 

Result data field initialized to all zero bits. 

data field 3 ( 33l»| I777 (27) ) 
060 061 662063 

test data ( 262| 15776 ) 

xxxxxxxxxxxx xxxxxxxxxxxx 063062061061 061061061061 
xxxxxxxxxxxx xxxxxxxxxxxx 
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STANDARD SCRIPTS 

A standard set of scripts is provided that can be used with eis_tester. If CPU 
problems with the EIS instructions are suspected, these scripts should be run. The ets 
segment's standard location in the storage hierarchy is >tools>ets, but an installation 
can locate ets somewhere else. 

EXAMPLES 

/'' An example to illustrate the interaction between 

* the "-do" and the "-cn" fields. 

inst mlr -ir tn -nt "-do and -cn interaction" 

-mfl idb ar reg -mf2 idb ar reg; 
/'>'' The uppercase letters in the two data statements could have been 

* typed in as "ABCDEFGH" and "CDEF" but were typed in as they are 
'< shown so that explanatory remarks could be placed on the adjacent 

'« lines. The symbols used above and below the desc and data lines 

* mean: 

* P The boundary of a page, and hence, also a word 

* boundary. 

" S S The operand string portion of the data field. 

" W A word boundary. 

* W P W iV 
desc 1 -cn 2 -ns 6;data 1 -do -5 "A" "B" "C" "D" "E" "F" "G" "H" "i" ; 
/* S S 

" Each uppercase letter in the above data statement occupies 9 bits. 

« Note that the data field for the first operand starts five 9"bit 
bytes to the left of a page boundary. This is due to the "-do -5" 

* field. However, the operand string excludes the first two bytes 

* of the data field, because of the "-cn 2" field. 

* p w *V 
desc 2 -cn 3 -ns i+;data 2 -do -1 000 000 000 "C" "D" "E" "F"; 

S S 

>» The data field for the second operand starts one 9~bit byte to the 

* left of the page boundary due to the "-do -1" field. The "-cn 3" 

" field results in the operand skipping over the first three bytes of 

* the data field. Another way to specify the CDEF string to fall 

" where it does would be to use these desc 2 and data 2 statements: 

ucS«« ^ iia *t 5 ua Lo £. uO £. uucr , 

* The "-cn 3" and 000 000 000 were used to show how to do it when 

* the person writing the script wants to use the CN field in the 

* second descriptor. «/ 
page -all; 
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COMMENT: The output from running eis_tester with the above script is shown 
COMMENT: below. Explanatory remarks have been inserted in the 
COMMENT: output, on the lines that start with COMMENT: 

ET 

TEST 1 (mlr) 

Test Description: -do and -cn interaction 

( 3^0|ltOOO ) Ind Desc. 



Eis instruction: 

000132100531 

it0003lt0001 u 

50001*30001 15 



-> 100007^00006 ( 3^1 

-> 200016600004 ( 3^2 



100 ) 
100 ) 



Pointer Registers: ( 3^*0 | 20 ) 

pro - pr3 77777|1 3^*^ 1 1766 (27) 345|1757 (27) 77777|1 

COMMENT: The value in the parentheses following a word offset, which 
COMMENT: is in octal, is the bit offset, in decimal. 

pri* - pr7 3^1 1^0 342|30 77777|1 77777|1 



ndex Registers: ( 340|70 ) 

xo - X7 17777 4 10 
A 000000017777 Q 



17777 ^ 5 Mill 
000000017777 



17777 



Test Indicators: 
000000000300 



( 340|111 ) 



This test takes 7 page faults. 

in2 idl dll dl2 id2 d21 d22 



COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 



Page d21 is included here because data_field_2 crosses the 
boundary between the first and second pages of the etd2 
segment. However, because of the "-cn 3" field, operand_2 
actually resides in only the second page. Therefore, the 
first page is not be touched, and no page fault occurs 
for page d2 1 . 



data field 1 



COMMENT: 



( 344 1 1776 (27) ) 
101 10210310ifl05 106107110111 

s — s 
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COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 



It is true that data_f i eld_l begins in bit 27 of word 1776 
However, because of the "-cn 2" field, operand_l begins 
with bit 9 of word 1777« The address development 
(in octal) for the start of operand_l is: 

ITEM SEGMENT I WORD 9-BITBYTE 



desc_l 
prl 

xl 

which is 



3U|1766 
Ok 



344 
344 



1775 
1777 



2 
3 

1 1 

1 



If the same calculations 
operand, it is seen that 



or 3^4|1777 (9) 
are carried out for the second 
the data field starts in 
one page but the operand starts in the next page. 
Refer to the script line above that contains the 
"desc 2" and "data 2" statements and then examine the 
adjacent 1 ines. 



data field 2 ( 345] 1777 (27) ) 

Result data field initialized to all zero bits. 



test data ( 340 | 15776 ) 

xxxxxxxxxxxx xxxxxxxxxxxx 000000000103 104l05106xxx 

COMMENT: S S 

COMMENT: The xxxxxx represent fill supplied by eis_tester. The nine 
COMMENT: leading octal zero digits are present because they were 
COMMENT: supplied in the "data 2" statement. 

xxxxxxxxxxxx xxxxxxxxx 



/'« An example to illustrate the interaction between 

* the "-do" and "-cp" and "-bp" fields. */ 

inst csl -bo or -nt "-do and -cp and -bp interaction" 

-mfl idb ar reg -mf2 idb ar reg; 
desc 1 -cp 2 -bp 3 "ns 30; 

/* The symbols used above and below the data lines mean: 
'< P The boundary of a page, and hence, also a word 

* boundary. 

* S S The operand string portion of the data field. 

>» W A word boundary. 

^ W P */ 

data 1 -do -J 123 456 701 020 203 040 123 ^56 765; 
/* S S 
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ft 

ft/ 

desc 

/ft 

data 

/ft 



Data_field_l starts seven 9~bit bytes before the page boundary, 
due to the "-do -7" field. The "-cp 2" field causes the processor 
to skip over the first two bytes (123 ^56 octal), so that 
operand_l starts somewhere in the 701 octal byte. The 
"-bp 3" field causes the processor to skip over the first three 
bits (7 octal) of the 701 byte, thereby starting at bit 30 
0-35) of the next to last word of a page. 



(bits numbered 
2 -cp 



1 -bp 6 -ns 30; 

Pxxx W W >'«/ 

2 -do 1 i+32 103 030 405 050 7^5 ^32 101; 

s s 

* The "Pxxx" above the "data 2" statement is intended to 

* indicate that the page boundary Is three octal digits (the xxx) 

* i.e., nine bits, before the start of data_f i e 1 d_2 , as 

* specified by the "-do 1" field. The "-cp 1" field specifies 

* skipping over the first 9"bit byte, to the 103 octal byte. 
" The "-bp 6" field specifies skipping the first six bits of 
>'« that byte, to the octal 3» which begins in bit position 2k 

* (of 0-35) in the first word of a page. 

ft WW sV 
data 3 ^32 103 132 425 35^ 7^5 ^32 101; 
/* S S 

* The "data 3" statement is used because the csl instruction 

* stores its result in the same bit locations from which the 

>» second operand was fetched. No "-do", "-cp", or "-bp" fields 

* are needed for the "data 3" statement because eis_tester 

ft associates the attributes of data__f i eld_2 and operand__2 with 

* the data supplied by the "data 3" statement, 
ft/ 

page -all; 



ET 

TEST 



1 (csl) 



Test Description: 
Eis instruction: 

007132060531 
4000340001 14 
5000430001 15 



■do and -cp and -bp interaction 
( 334 1 4000 ) Ind Desc. 

-> 100007430036 ( 335 

-> 200016260036 ( 336 



100 ) 
100 ) 
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Pointer Registers: { 33^|20 ) 

pro - pr3 777771 r 3^0 1 1766(9) 3^1|1760(9) 77777|1 
prk - pr7 3351^0 336 | 30 77777 |1 77777 |1 

Index Registers: ( 33^)70 ) 

XO - X7 17777 W 110 17777 h 5 17777 17777 
A 000000017777 Q 000000017777 

Test Indicators: ( 33'»|111 ) 
000000000200 



This test takes 7 page faults. 

in2 idl dll dl2 id2 d22 d32 
COMMENT: Page dl2 is listed here because data_fie1d_l is in both 
COMMENT: pages 1 and 2. However, operand__l is, in only page 1, 
COMMENT: so a page fault does not occur for page dl2. 

data field 1 ( 3^0|1776(9) ) 

123^*56701 020203040123 456765 
COMMENT: S S 



data field 2 ( 3^1 12000(9) ) 

432103030 405050765432 101 
COMMENT: S S 

COMMENT: The address development for the start of operand_2 is 
COMMENT: shown below. For x2, 110 octal « 72 decimal « 2 words 
COMMENT: and no bits. 

COMMENT: 9-BIT BYTE BIT IN 



COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 
COMMENT 



ITEM 



desc 2 
pr2 ~ 
x2 



(OCTAL) 



16 

341 1 1760 
2 



(BINARY) 



01 
01 
00 



(BINARY) 



0110 
0000 
0000 



341 1 2000 



10 



0110 



which is segment 3'»1> word 0 of the second page, 9-bit 
byte number 2 (numbering is 0-3) > and bit number 6 
(of 0-8) . i .e. . 3^1 1 2000 (24) . 



test data 

xxxxxxxxxxxx 
COMMENT: 
COMMENT: 
COMMENT: 
COMMENT: 
COMMENT: 



( 53^ '23776 ) 
xxxxxxxxxxxx '432103132425 354765432101 

S S 

The leading fill of 43210 and the trailing fill of 
765432101 were not affected by the execution of the 
instruction, proving that bits outside the operand 
strings did not enter into the instruction's execution. 



xxxxxxxxxxxx xxxxxxxxxxxx 
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SYNTAX AS A COMMAND 
enteral ss path 
FUNCT/ON 

causes the command processor to compare each command to a supplied Limited Service 
Subsystem (LSS) control segment, which was created using the make_commands 
command. Any command not found in the control segment is refused. Those found 
are mapped into the command specified by the control segment 

ARGUMENTS 

path 

is the pathname of the LSS control segment 
NOTES 

The LSS control segment must be previously created with the make_commands 
command. The command line as shown in the example above is usually included in 
the project_start_up.ec. See the make_commands command for more details on the 
LSS facility and the use of the project_start_up exec__com. 

EXAMPLES 

To limit users on a project to a subsystem as specified in an LSS control segment 
named student_commands. place the following command line in their project_start_up.ec: 

enter Iss >udd>Students>student commands 



Name: excerpt^jnst 
SYNTAX AS A COMMAND 
excerpt_mst ree1_id {names} 

FUNCT/ON 

I selects given s^ments from a system tape (a BCE/Multics bootload tape). 



11/86 
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ARGUMENTS 
reel_id 

is the reel identification number of the tape to be extracted. The reel 
identification number, which is site dependent, can be up to 32 characters long. 
The reel_id can also include a density specification to indicate the density of the 
tape being excerpted, as in "060341, den= 1600". 

names 

are the names of the specific segments to be extracted. The star convention is 
allowed. If you supply no names, all of the segments on the tape are extracted. 
If a given segment has separate linkage and definitions on the tape and has been 
extracted, the separate linkage and definitions are extracted as well. Segments 
extracted are created in the current working directory. Bit counts are set from 
the SLT entry on the tape, as opposed to the actual length of the segment on the 
tape. 

NOTES 

A message is printed whenever a segment is extracted. A diagnostic is issued if you 
provide names that match no segments on the tape. 



Name: exercise disk 

SYNTAX AS A COMMAND 

exerc i se_d i sk disk_type vo1ume_id {-control__args} 
FUNCT/ON 

exercises a disk drive. Maximal arm motion occurs all over the disk, and data is 

written and read back later for checking at each poinL This activity can be used to 
make unstable drives fail repeatedly. 

ARGUMENTS 

disk_type 

a valid Multics disk device type {e.g., d451, d500, and d501). 
volume_id 

the label of the disk pack on which the test is to be run. 
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CONTROL ARGUMENTS 
-write_read, -wr 

writes a known pattern over the entire disk pack, and then reads this information 
back for checking purposes. This is the default. 

-write, -w 

writes a known pattern over the entire disk pack. The default is -write_read. 
-read, -r 

reads back the information on the disk pack, for checking purposes. The default 
is -write_read. 

-device STR, -dv STR 

specifies the device on which you want to run the test, where STR can be 

dska_02, dskb_13, etc.). Either this control argument or the assign_resource (ar) 

command must be used to attach an I/O disk. 

-no_data_compare, -ndc 

makes no data compare on the read pass; only errors detected by the hardware 
are reported. This enables testing of a disk pack without knowing what data is 
recorded on it. The default is to compare the data with a known pattern. 

-random 

the test performs random rather than sequential seeks; the test takes several hours. 
This is the default 

-sequential, -sq 

the lest runs sequentially, writing and reading from sector 0. 

-alternate_track, -altrk 

removes the alternate track area of the disk from the test parameters. The 
default is to use the entire pack. 

-from M, -fm M 

sets the lower limit of the range of addresses to be tested to M, where M is a 
decimal integer specifying a valid cylinder number for the device to be tested. 

-to N 

sets the high limit of the range of addresses to be tested to N, where N is a 
decimal integer specifying a valid cylinder number for the device to be tested. 
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NOTES 

The exercise_disk command requests the mounting of a scratch pack. 

The assign_resource command must be used in conjunction with this command to 
exercise a given drive. Such drives must be configured as user I/O drives (nonstorage 
system) via the udsk config card (described in the Multics System Maintenance | 
Procedures manual. Order No. AM81) or by the use of the set_drive_usage (sdu) | 
initializer command. 

When the -from or -to control arguments are used, testing is confined to the range 
of addresses specified. The seek pattern used in this mode is from inner cylinder to 
outer cylinder, with M incrementing to N or the maximum address of the device, and 
N decrementing to M or cylinder zero. When M reaches its inner limit, the pattern 
is repeated. Testing continues until you stop it, by hitting the break key and then 
typing the release (rl) command. 



Name: file ^system^ meters, fsm 

SYNTAX AS A COMMAND 
fsm {-control_args} 
CI iMr-TinM 

used to meter certain storage system variables and functions. 

CONTROL ARGUMENTS 

-ast 

prints certain meters about active segment table (AST) usage, 
-brief, -bf 

generates a shortened report. Those meters not printed if -brief is specified are 
indicated by a plus (+) in "Notes" below. 

-page, -pg 

prints certain m.eters about paging. 

-report_reset, -rr 

generates a report and then performs the reset operation. The report can be 
shortened by using the -brief control argument 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 
the last call with -reset specified. If -reset has never been given in a process, it 
is equivalent to having been specified at system initialization time. 
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ACCESS REQUIRED 

This command requires access to phcs_ or metering_gate_. 
NOTES 

If the file_system_meters command is given with no control arguments, it prints a full 
report. 

The following meters, which reflect the activity of the AST lists, are printed if the 
-ast control argument is specified. The two columns printed by this command contain 
the number of occurrences of the specified item and the average time between 
occurrences. 

Activations 

is the number of segment activations. 

segfault 

is the number of activations caused by segment faults; also expressed as a 
percentage of all activations. 

makeknown 

is the number of activations not caused directly by segment faults, but 
resulting from explicit calls from the makeknown_ routine: also expressed as a 
percentage of all activations. 

backup 

is the number of activations resulting from calls to activate$backup_activate: 
also expressed as a percentage of all activations. 

directories 

is the number of directories activated; also expressed as a percentage of all 
activations. 

Deactivations 

is the number of segment deactivations. 

Demand deactivate 

attempts 

is the number of deactivations explicitly requested by users, 
successes 

is the number of demand deactivations which succeeded; also expressed as a 
percentage of attempts and as a percentage of all deactivations. 
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Seg Faults 
fault 

is the number of segment faults. 

call 

is the number of calls to the segment fault handler to activate a segment 
without taking a segment fault; also expressed as a percentage of segment 
faults. 

activations 

is the number of segment faults that resulted in an activation; also expressed 
as a percentage of segment faults. 

Bound Faults 

is the number of bound faults. 

+ Setfaults 

is the number of setfaults performed during segment deactivation and during the 
handling of bound faults. Setfaults are segment faults forced when dynamic 
segment attributes are changed (e.g., access to a segment is revoked by another 
process). 

access 

is the number of setfaults performed because the access was changed on a 
segment; also expressed as a percentage of all setfaults. 

+ ASTE Trickle 

is the number of times the VTOCE was updated from the ASTE because the 
information in the VTOCE was noticed to have changed during ASTE allocation. 
ASTE Trickle is a hedge against system crashes, as it updates ASTEs into the 
VTOCEs periodically, rather than on demand. 

+ Steps 

is the number of steps taken through the AST lists searching for a free, usable 
AST entry. 

+ Skips 

is the number of times an entry was skipped; also expressed as a percentage of 
Steps. 

+ ehs 

is the number of times an entry was skipped in the search for a free, usable 
entry because the entry-hold-switch was on. The entry-hold-switch is set for 
certain segments that cannot be deactivated. Also expressed as a percentage of 
Skips. 

+ mem 

is the number of times an entry was skipped because it had pages in memory; 
also expressed as a percentage of Skips. 
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+ init 

is the number of times an entry was skipped to give it a grace lap after all of 
its pages were removed from core; also expressed as a percentage of Skips. 

+ Searches 

is the number of full AST searches required because no entry was readily 
available. 

+ Avg. Cost 

is the, average "cost" in I/Os of deactivations arising from full searches. 
Cleanups 

is the number of calls to cleanup. The percentage of real time spent in cleanup 
is also given. 

Force writes 

is the number of calls to force_write. The three following meters relating to 
force_writes are printed only if any force_writes occurred. 

without pwrites 

is the number of times force_write wrote no pages. 

pages written 

is the number of pages written by force_write. 

force updatev 

is the number of calls to update_vtoce resulting from force_writes. 

Lock AST 

is the number of lockings of the AST. 

The following meters provide information about AST lock contention. 

AST locked 

is the average real time during which the AST lock is held locked and the 
percentage of the metering interval during which the AST was locked. This 
percentage cannot exceed 100%, and the closer the 100% figure is approached, the 
more AST lock contention becomes the limiting function in system throughput. 

AST lock wailing 

is the average real time delay between an attempt to lock the AST and successful 
locking of the AST. The total real time spent by all processes waiting for the 
AST lock, expressed as a percentage of the metering interval, is also given. This 
number may exceed 100% if, on the average, more than one process was waiting 
for the AST lock. 

The following items represent a table indexed by page table size and they show the 

activity and use of the four AST lists. 
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AST Sizes 

indicates the page table sizes being used by the system (constant). 
Number 

is the number of entries of the specified size. 
Need 

is the number of entries of the specified size that were needed. 
Steps 

is the number of steps taken while scanning the specified list 
Ave Steps 

is the average number of steps taken in the specified list to find a usable entry 
in the list 

Lap Time (sec) 

is the average time for the replacement algorithm to make one pass over the list 

The following meters are printed if the -page control argument is specified. The two 
columns printed by this command contain the number of occurrences of the specified 
item and the average time between occurrences. 

Needc 

is the number of times a frame of main memory was needed (for page faults, 
process loadings, etc.). 

Ceiling 

is the number of times too many write requests were queued at once. Not 
printed if zero. 

Claim runs 

is the number of times the page removal algorithm could not queue an additional 
write until a previous write was completed. If the average time between claim 
runs is less than .010 minutes, then an I/O bottleneck probably exists in the 
system. If the value of claim runs is zero, then the value is not printed. 

Ring 0 faults 

is the percentage of page faults that occurred while executing in ring 0. 
PDIR faults 

is the percentage of page faults that occur on pages of segments in process 
directories. 

Level 2 faults 

is the percentage of page faults on pages of segments in directories directly off 
the root. This is a measure of the activity of the system libraries, hhw 

DIR faults 

is the percentage of page faults on directory pages. 
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New Pages 

is the percentage of page faults that resulted in the creation of pages. This 
happens because the page faulted has never been referenced or logically contains 
all zeros. 

Volmap_seg 

is the number of page faults taken on free storage maps; also expressed as the 
average time between faults. 

Zero pages 

is the number of page writes that were avoided because the page to be written 
contained all zeros. In general, pages of zeros are not written to disk but are 
converted to null addresses (an indication in the file map for the segment that 
the page is logically zero). Also expressed as the average time between zero pages. 

I Segment State Change 

I is a measure of suspected covert channel activity- 
audited 

is the number of times all processes performed suspected covert channel 
segment state changes at a rate execeeding the system-defined limit 

I delayed 

I is the number of times all processes had to be delayed in order to keep the 

I rate of suspected covert channel segment state changes within the system-defined 

I limit. 

I avg. 

I is the average time processes were delayed. 

Laps 

is the number of times the used pointer has gone around the main memory used 
list in the search for a usable block of main memory. 

+ Steps 

is the number of steps taken around the main memory used list A step consists 
in moving the used pointer to the next entry on the list 

+ Skip 

is the number of times a page was skipped; also expressed as a percentage of 
Steps. 

+ wired 

is the number of times a page was skipped while searching the main memory 
used list because it was wired down; also expressed as a percentage of Skip. 

+ used 

is the number of times a page was skipped because it was used in the last lap; 
also expressed as a percentage of Skip. 
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+ mod 

is the number of times a page was skipped because it had been modified; also 
expressed as a percentage of Skip. 

+ fc pin 

is the number of times a page was skipped by find_core because it was pinned; 
also expressed as a percentage of Skip. 

+ cl pin 

is the number of times a page was skipped by claim_mode_core because it was 
pinned; also expressed as a percentage of Skip. 

pages 

is the number of pages available in the system. This is the total main memory 
minus the permanently wired down supervisor. 

wired 

is the number of pages temporarily wired down. This includes descriptor segments 
and process data segments (PDS) for loaded processes. 

Average steps 

is the average number of stej» taken around the main memory used list to find a 
usable frame of main memory. 

EXAMPLES 

The following is an example of the information printed when the file_system_meters 
command is invoked with no control arguments. (Appendix A contains a representation 
of the configuration deck used to create the system from which the metering samples 
were taken.) 
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! f i le__system__meters 
Total metering time 



0: 15:23 



Activations 2227 

segfault I786 

makeknown iS^t 

backup 257 

directories 2^2 

synch 2 

Deactivations 2225 
Demand deactivate 

attempts 6 

Seg Faults 10571 

fault 8972 

call 1599 

activations I786 

Bound Faults k}k 

Setfaults 10325 

access 32 

ASTE Trickle 212 

Steps 9283 

Skips 6568 

ehs 756 

mem I93O 

init 3882 

Searches 0 

Cleanups 2279 

Force wr i tes 3^31 

pages written 6IOI 

force updatev 17 

Lock AST i+itOlO 



ATB 

0.415 sec. 

0.517 sec. 

5.021 sec. 

3.595 sec. 

3.818 sec. 
461.961 sec. 

0.415 sec. 



153.987 
0.087 
0. 103 
0.578 
0.517 
2. 129 
89.484 

28.873 
4.358 

99.528 
0.141 
1 .222 

0.479 
0.238 
0.000 
0.405 
0.254 
0.151 
54.348 
0.021 



sec . 
sec . 
sec . 
sec . 
sec . 
sec . 
msec 
sec . 
sec . 
msec 
sec . 
sec . 
sec . 
sec . 
sec . 
sec . 
sec . 
sec . 
sec . 
sec . 



80.198% of all 
8.262% of all 
1 1 .540% of al 1 
10.867% of al 1 
0.090% of all 



84.874% of Seg Faults 
15.126% of Seg Faults 
16.895% of Seg Faults 



0.310% of setfaults 



70.753% of Steps 

1 1 .510% of Skips 

29.385% of Skips 

59.105% of Skips 

0.7 % of real time 



AVE/lock 



% 
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AST locked 


5.871 


msec. 280O 






AST lock wai ting 


9.579 


msec. kS'^ 






AST Sizes 


k 


16 


64 


256 


Number 


3500 


1500 


750 


365 


Need 


1935 


565 


179 


36 


Steps 


6259 


2122 


793 


109 


Ave Steps 


3.2 


3.8 


k,k 


3.0 


Lap Time (sec) 


516.7 


653.1 


873.8 


3093.9 




# 


ATB 







Needc 11 9620 

Ring 0 faults 
PDIR faults 
Level 2 faults 
DIR faults 
New Pages 

Volmap_seg 0 
Zero pages 126^* 
Seg state chg. 

delayed 2 
audited k 
Laps 7k 
Steps 654084 
Skip 579739 
wired 3589 
used 190026 
mod 269202 
fc pin 65647 
cl pin 45275 



7.724 msec 

15.446 % 

50.083 % 

1 1 .880 % 

9.162 % 

12.417 % 

0.000 msec 

730.951 msec 



461 .961 
230.981 
12.485 
1 .413 
1.594 

-/^ . 

4.862 
3.432 
14.074 
20.407 



sec . 
sec . 
sec . 
msec 
msec 

me 

msec 
msec 
msec 
msec 



0.2 sec. avg. delay 



88.634% of 
] .654% of 
32.778% of 
46.435% of 
11.324% of 
7.810% of 



Steps 

Sk i p 
Sk i p 
Skip 
Skip 



8826 pages, 203 wired. 
Average steps 5.468 
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Name: fim meters 

SYNTAX AS A COMMAND 

fim_meters {f aul t__name} {-contro1_args} 

FUNCTION 

interprets and prints per-system metering information on central processor faults. 

ARGUMENTS 

fault_name 

is the name of a single fault type (valid fault types are listed under "Notes" 
below). Only the information for that fault type is printed. If fault_name is not 
specified, then information for all fault types is printed. No control argument can 
be given if a fault_name is specified. 

CONTROL ARGUMENTS 

I -cpu {tagl.-.tagN} 

I displays fault counts for those processors specified by tagi. Tag may be one of 
I the letters a through h or A through H. If tag is omitted, all processors are 
} select^. 

-long, -Ig 

prints information on software-interpreted subordinate faults with each associated 
hardware fault 

-report_reset, -rr 

generates a full report and then performs a reset operation. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 
the last call with -reset specified. If -reset has never been given in a process, it 
is equivalent to having been specified at system initialization time. The metering 
interval is reset for ALL processors. 

-sort {STR} 

sorts the output as specified by STR, which can be either "count" or "number". 
If STR is not specified, the output is sorted by count. If this control argument is 
not specified, the output is sorted by hardware fault number. 

I -total, -tt 

j displays total fault counts for all processors. This is the default. 
ACCESS REQUIRED 

This command requires access to phcs_ or metering. gate, . 
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NOTES 



If both -long and -sort are used, subordinate faults are sorted within associated 
hardware fault. 



The following is a brief description of the variables printed by the fim_meters 
command. 



type 

is the name of the hardware fault. 



count 

is the total number of times the fault occurred on any central processor 
configured. 

The following are the valid names of hardware faults. These names are printed 2S 
"type" and can be used as the fault_name argument Full descriptions of these faults 
can be found in the Multics Processor Manual, Order No. AL39. 



access_vi elation, acv 
command, cmd 
connect, con 
derai 1 , dr 1 
directed_fault_2, df2 
di rected_faul t_3, df3 
divide_check, div 
execute, exf 
fau1t_tag_l, ftl 
fault_tag_3, ft3 
i 11 egal_procedure, i pr 
1 i nkage__f aul t, f t2 
lockup, luf 



mmel , mme 

mme2 
mme3 
mme4 

op_not_compl ete, one 
overflow, ovf 
page_fault, dfl 
parity, par 
segment_f au It, df 0 
shutdown, sdf 
startup, suf 
store, str 
t imer_ranout, tro 
trouble, trb 



Subordinate faults are recursive calls to the main fault processor that can be 
interpreted as subcases of hardware faults. For example, the hardware generated 
"command" fault may be interpreted as an isot_fault, a lot_fault, or a command_fault, 
depending on other conditions at the time of the fault. A complete description of 
subordinate faults would require a description of Multics fault processing, and is 
beyond the scope of this manual. 



EXAMPLES 



The following is an example of the information printed when the fim_meters 
command is invoked with no control arguments. (Appendix A contains a representation 
of the configuration deck used to create the system from which the metering sample 
was taken.) 
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Total Metering Time: 



56:li4:39 



Fault Type 
mmel 

f aul t_tag__l 
t imer_runout 
command 
dera i ,1 



Total Fault Count 



231^9 
]k 

k026Ske 
302 
111 
32565031 



connect 

i 1 legal_procedure 

overflow 

d i vi de_check 

segment_f aul t 

page_f aul t 

access_vi ol at i on 

mme2 

1 i nkage_f aul t 



591202 
5919620 
^52383 



12 

1380667 



29 
2it6 

651 



Name: fix quota used 

SYNTAX AS A COMMAND 
f i x_quota_used path 
FUNCTION 

repairs inconsistencies in storage system quota used for a directory. 

ARGUMENTS 

path 

is the pathname of the directory for which quota is to be made consistent 
ACCESS REQUIRED 
Access to the hphcs_ gate is required. 



The normal use of this command is from the fix_quota_used.ec exec_com, or by the 
"x repair" operator command. When a quota (segment quota or directory quota) is 
found inconsistent and corrected, a message is printed. If the correction causes a 
directory to have greater quota used than allocated, another message is printed. 



NOTES 
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Name: flush 

SYNTAX AS A COMMAND 
flush {-control_arg} 
FUNCTION 

causes excessive paging activity in order to time the system. It is not to be used 
casually as it impairs service to all users of the system. 

CONTROL ARGUMENTS 

-temp_dir path, -td path 

specifies that temporary segments used for flushing main memory are to be 
created in the directory identified by path (the default is to create them in the 
process directory). 

NOTES 

In order for all pages in main memory to be flushed, the directory used for 
temporary segments must have sufficient quota for as many pages as there are in main 
memory. 



Name: fnp data summary 

SYNTAX AS A COMMAND 

f np_data_summary {fnp_names} {-control__args} 
FUNCT/ON 

reports error statistics recorded in the syserr log by the poll_fnp command. The 
statistics reported include parity errors for all channels and various counters for 
synchronous channels whose interpretation depends on the line type of the channel. 
Only nonzero statistics are reported. 

ARGUMENTS 

fnp_names 

are the names of FNPs for which statistics are to be reported. If no fnp_names 
are specified, statistics are reported for all FNPs for which any nonzero statistics 
are available. 
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CONTROL ARGUMENTS 
-expand 

displays in expanded form every entry in the syserr log containing statistics for 
the specified FNP(s). 

-extend, -ext 

appends the output of the command to the end of the output_file if it already 
exists. This control argument can be specified only if -output_file (below) is 
specified. 

-from DATE_TIME, -fm DATE_TIME 

starts scanning the syserr log from the time specified by DATE_TIME, which 
must be a character string acceptable to convert_date_to_binary_ (described in the 
Mufti cs Subroutines and 110 Modules manual. Order No. AG93). The default 
is to start at the beginning of the log. 

-for TIME 

restricts the scan of the syserr log to an interval of length TIME, where TIME is 
a character string representation of a time interval in a form acceptable to 
convert_date_to_binary_ (described in the Multics Subroutines and 110 Modules 
manual. Order No. AG93). This control argument is incompatible with -to 
(described below). The default is to continue the scan up to the end of the log. 

-output_file {PATH}, -of {PATH} 

directs output to a file. If PATH is specified, it is the pathname of the output 
file; otherwise, output is sent to fnp_data_summary. output in the current working 
directory. If -output_file is not specified, the default is to direct output to your 
terminal. 

-to DATE_TIME 

ends the scan of the syserr log at the time specified by DATE_TIME, which 
must be a character string acceptable to convert_date_to_binary_. This control 
argument is incompatible with -for (above). The default is to continue the scan 
to the end of the log. 

ACCESS REOUIRED 

Read permission is required on the log segments themselves and status permission is 
required on their containing directories. 
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Name: fnp throughput 

SYNTAX AS A COMMAND 

f np_throughput {fnp_id} {-control_arg} 

FUNCTION 

reports character throughput for an FNP or all FNPs and optionally allows the 
resetting of the metering interval. 

ARGUMENTS 

fnp_id 

is the name of an FNP or "*", which means all currently running FNPs. This 
argument must be specified unless the -reset control argument is specified, in 
which case fnp_id must not be specified. 

CONTROL ARGUMENTS 

may be either, but not both, of the following. If neither is specified, information 
is printed and the metering interval is not reset. 

-report_reset, rr 

causes statistics to be printed and the metering interval to be reset. If this 
control argument is specified, fnp_id must be specified. 

-reset, -rs 

causes the metering interval to be reset without printing any statistics. If this 
control argument is specified, fnp_id must be omitted. 

NOTES 

The start of the metering interval in effect is measured from the time the FNP was 
last booted, or from the time the interval was last reset, whichever was the most 
recent event. 

The reset action of the -report_reset control argument applies to the metering interval 
for all FNPs, even though the command invocation is specific to the statistics for a 
particular FNP. 
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EXAMPLES 

To report on throughput statistics for FNP "a", while resetting the metering interval, 
specify: 

f np_throughput a -repor t_reset 
The output would appear as follows: 

input output 
Characters transmitted 71,966,400 9it,934,itOO 
Characters per second 4,700 6,200 



Name: format disk pack, fdp 

SYNTAX AS A COMMAND 
fdp operation -control_args 
FUNCTiON 

provides a means of formatting 451 disk packs online under Multics. This command 
cannot be used to format fixed media devices (MSU0500 and MSU0501 disks). An 
I/O disk drive must be available in the configuration to allow this command to 
operate. 

In general, all disk packs should be formatted during Multics operation by using the 
online T&,D tool, MTR, under TOLTS and MOLTS. Procedures for formatting both 
MSU0451 and MSU0500/MSU0501 disk packs with MTR are described in the Multics 
Online Test and Diagnostics Reference Manual, Order No. AU77. 

ARGUMENTS 

operation 

is one of the following operations to be performed on the specified disk pack: 
read_pack 

each track header of the disk pack is read and data is accumulated on all tracks 
that are formatted "defective." After all disk pack headers are read, a summary 
of the defective tracks is displayed on the user's terminal. 

format_pack 

each track header is read and the track condition is interrogated. A format_track 
command is then issued, using the information from the previous track condition 
in the following manner: 
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If the -nodef control argument is not specified, all the tracks are reformatted 
according to the current format condition. 

If the -nodef control argument is specified, all tracks are reformatted as "good" 
regardless of the previous track condition. 

Data on the original track condition (as determined by reading the track header) 
is retained and displayed, after the entire disk pack has been formatted. Tracks 
are formatted as defective only if they are marked as defective in the track 
header information of each track. 

read_track 

a request loop is entered (see "Notes" below) and the user is asked to type in the 
cylinder and head address of a particular track. A read track header is then 
issued to the requested track and the track condition is displayed on the user's 
terminal. The program remains in the request loop until the user issues the quit 
request. 

format_track 

a request loop is entered (see "Notes" below) and the user is asked to enter the 
track address and the desired track condition; a format track is then issued to the 
requested track address, formatting the track with the user specified track 
condition. If the requested track condition is defective with alternate assigned, the 
program searches for the next available alternate track, formats this track as 
alternate and displays the alternate track address to the user. The program 
remains in the request loop until the user issues the quit request. 

read_label 

the format label record is read and its contents displayed in an interpretive 
format. 

CONTROL ARGUMENTS 

-hbypass 

(header bypass) sets the format track control bits so that no check of the track 
header matching the seek address is made by the hardware. Indiscriminate use of 
this control argument is not advised. It is recommended that the -hbypass control 
argument be used only when formatting packs that have been degaussed or 
otherwise erased. 

-hold 

allows the user to go into an option loop after the current operation is complete 
so that he may select another operation without releasing the disk pack. The user 
may exit from the option loop by issuing the quit request instead of the 
operations described above. 

-model ID 

specifies that ID is the disk pack model (e.g., m400, m451). Default is the m400 
model. 
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-nodef 

forces all tracks to be formatted as "good" regardless of the previous track 
condition. This control argument is valid only for the format_pack operation. 

-system 

is required for the mounting and formatting of Multics storage system volumes. 
In the case of a new pack, if the system can't read the pack's label, it will 
assume that the pack is a storage system pack. Thus, the -system control 
argument should always be used with a new pack, to avoid any possibility of 
problems. In fact, the only time -system should not be used is when the volume 
has been previously formatted and is not a storage system volume. Access to the 
privileged gate rcp_sys_ is needed for use of this control argument 

-volume ID 

specifies that ID is the pack label name. This control argument is always 
required, so the system can tell you the name of the disk to be mounted. 

NOTES 

Input to the read_track request loop is of the form: 
ccc, hn 



qui t 

where: 
ccc 

is the cylinder number. 

hh 

is the head number. 

quit 

is the exit from the request loop. 
The track's condition is then displayed on the user's terminal. 
Input to the format_track loop is of the form: 
ccc, hh, key 

or: 

qui t 
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where: 
ccc 

is the cylinder number. 

hh 

is the head number. 

key 

is any of the following: 
good 

formats the track as good. 

defa 

formats the track as defective and assigns an alternate. 

def 

formats the track as defective. 

quit 

is the exit from the request loop. 
The track^s new condition is displayed on your terminal 
DEFECTIVE DISK TRACK HANDLING 

The last three cylinders of a disk pack can be reserved for use as an alternate track 
area. The tracks of these cylinders may be pointed to by the track headers of 
defective tracks. The disk controller automatically references an alternate track when it 
encounters a reference to a track marked as defective with an assigned alternate. Such 
a reference requires at least two additional rotations of the disk. 

This command allows you to format a disk pack under Multics operation, and to 
redirect defective tracks to the alternate track area of a disk pack. 

You can*t normally reference directly a disk track defined as alternate. You can 
usually reference it by making a reference to the defective track redirected to that 
alternate. Therefore, when a disk pack contains alternate tracks, you must carry out 
certain procedures for successful BCE/Multics operation. These are described in the* 
following paragraphs. 
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SCEIMULTICS ORERATIGN WITH ALTERNATE TRACKS 

If alternate tracks are to be defined on a new disk pack, you must define a special 
partition when that pack is initialized as a Multics storage system volume. You use 
the init_vol command for this purpose. Always give -special with init_vol if the pack 
being initialized contains alternate tracks. The first partition defined must be the 
partition containing the alternate track area, which you accomplish by typing 

part alt high 141 

which defines the ALT partition to ensure that Multics makes no other use of the 
disk pack area reserved for alternate tracks. 

If you define no ALT partition, Multics may attempt, at some future time, to utilize 
the ALT track area of the ' disk as part of the storage system hierarchy, with 
disastrous results. 

When a storage system volume is copied and rebuilt onto a new volume, you must 
define the ALT partition as above in the invocation of the rebuild.disk command. 



Name: generate_mst, gm 

SYNTAX AS A COMMAND 

gm path reel__id {-control_args} 

FUNCTION 

generates a BCE/Multics system tape that can later be "bootloaded" by BCE as the 
first step in bringing up a Multics system. 

ARGUMENTS 

path 

is the pathname of the header segment without the header suffix. 
reel_id 

is the reel identification number of the tape from which information is to be 
copied. This reel identification number, which is site dependent, can be up to 32 
characters long, and can include a density specification to indicate the density of 
the tape being written, as in **060341,den"1600'*. 

CONTROL ARGUMENTS 

-directory, -dr 

puts a search rule segment in your working directory. The name of the search 
rule segment is path.search, where path is the entryname portion of the pathname 
given. 
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-file, -fl 

directs output to a file in the storage system rather than to a tape. The file 
name (which can specify a multisegment file) has the same name as the reeljd 
argument 

-hold 

does not detach the tape when generation is completed. You can then perform a 
checker run on the same tape without remounting the reel. 

-notape 

does not generate a tape. You can use it to check the consistency of the header 
segment and produce an output listing without actually generating a tape. 

-sysjd STR, -sysid STR 

sets the system identifier to STR. which can be up to eight characters long. If 
you omit it, the first eight characters of the entryname portion of the pathname 
given are used by default 

-versjd STR, -versid STR 

sets the version identifier to STR, which can be up to eight characters long. If 
you omit it, the first eight characters of the entryname portion of the pathname 
given are used by default 

FORMAT OF A SYSTBM TAP£ HEA£>ER 

A system tape header is an ASCII file (in free format) consisting of keywords 
followed by optional control arguments. You can place comments anywhere in the 
header, except within a keyword name or control argument, and can separate them by 
"/*" and "*/". 

There are two levels of keywords: major and minor. The fabricate, first_name, name, 
object and text keywords are initial keywords and indicate the start of a description 
of control arguments for a single segment to be placed on the system tape. The 
linkage keyword is only valid if found in a s^ment description list (SDL). The end 
keyword indicates the end of an SDL. The collection keyword, which cannot occur in 
an SDL, instructs the generator to write a collection mark on the system tape. The 
fini keyword, which cannot occur within an SDL. instructs the generator to close out 
the tape by writing an EOF and dismounting it 

The syntax of the header consists of some SDLs, occasionally separated by collection 
keywords and ending with a fini keyword. 

Keywords having no arguments are followed immediately by semicolons; those having 
arguments are followed immediately by a colon, which is followed by arguments^ 
separated by conmias. The arguments end with a semicolon. 
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LIST GF MAJOR KEYWORDS 
add.segnames 

adds the segnames defined in an object segment to the list of names for that 
segment, as if they had appeared in the list following an "object" or a "name" 
statement. All names that appear as segname definitions in the object segment are 
added to the list of names for this segment. You can only use this keyword in 
the SDL for a bound object segment immediately after the keyword that begins 
the SDL. You can usually use it to replace the list of names associated with a 
bound segment 

boot_program 

begins the definition of a segment that is placed in the bootload portion of the 
system tape label. The bootload_program portion of the system tape label is 
executed when the initialize/bootload sequence is executed by the lOM switch or 
OC conwnand sequence. Only the text section of the program is placed on the 
tape, and it must be less than 1500 (octal) words long; if shorter, it is padded to 
1500 words with NOP instructions. Put this keyword first in the header file. It is 
incompatible with the first_name keyword. 
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collection 

writes a collection mark indicated by N on the tape containing the collection 
number that follows the collection keyword. Put this keyword between segments, 
not in a segment definition. 

data names 

begins a list of names associated with the segment. This keyword places the 
complete named segment on the tape, preceded by a preface area containing all 
the information specified in the SDL. The data keyword is used only for 
segments that are not Multics standard object segments, such as ASCII files. The 
data and linkage keywords are incompatible. 

delete_name names 

removes extra names from the list of names for the current segment that were 
added with the add_segnames statement but that should not appear on the 
segment Like add_segnames, you can usually use it to replace the list of names 
associated with a bound segment. It must appear after add_segnames in an SDL. 

end 

specifies the end of a segment definition. This keyword must conclude every use 
of an object, name, first_name, fabricate, or text keyword. 

fabricate names 

makes an all-zero segment and plac^ it on the tape; names is a list of names 
associated with the segment. The attributes for the segment are derived from the 
SDL. The fabricate and linkage keywords are incompatible. 

fini 

specifies the end of a system tape header. Any keywords appearing in the header | 
after the first fini keyword are ignored. 

first_name name 

indicates that the named segment associated with this SDL is the first segment on 
the tape and is specially processed; i.e., the first 32 decimal words of the segment 
are overwritten with tape header information when the tape is bootloaded. 
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linkage 

places the linkage and definitions sections of an object segment on the tape, 
following the object segment itself (if you used the object keyword to define it) 
or the text section (if you used the name or text keywords). The linkage keyword 
must appear in an object definition between the object, text, or name keyword 
for the segment and the end keyword. Any minor keywords following a linkage 
keyword (e.g., wired) are applied to the linkage section rather than to the text 
section; you can use this to direct the linkage section into a different 
supervisor-combined linkage segment than would be used by default. You must 
supply the linkage keyword to include definitions on the tape and copy them into 
the supervisor definitions segment, even if the segment has no linkage section. 
This is often true for object segments created with create_data_segment. If an 
object segment is used by the supervisor, place its definitions sections on the tape 
by specifying the linkage keyword, even if the segment is started with the object 
statement, so that the definitions section is included along with the text section. 

name names 

places the named segment on tape preceded by a preface area for the segment 
containing all the information specified in the SDL. If the linkage keyword is 
found in the SDL, the generator splits apart the object segment named and places 
only the text on the tape. Then the linkage section by itself (preceded by a 
preface area for the linkage section) follows the text and definitions section 
(preceded by its preface) on the tape. Otherwise the entire object segment is 
placed on the tape. Use this keyword for nonobject segments. For a BCE/Multics 
system tape, the names specified in the header for a segment are the only ones 
by which you can reference the segment Extra nam^ on the segment itself are 
ignored. When adding a new program to an existing bound segment, update the 
system tape header, as well as the bindfile, before adding the name of the new 
program to the list of names for the bound segment. 

object names 

behaves exactly as the name keyword except that the entire object segment is 

placed on tape rather than just the text section. It is also followed by the 

(redundant) linkage and definition sections if you use the linkage keyword. 

text names 

places the text section alone on tape. Use this keyword if you want only the text 
part of an object segment. 

LIST OF MINOR KEYWORDS 

abs_seg 

is either yes or no. Indicates whether or not to suppress creation of a segment 
when current length /maximum length is not zero. 

access 

is the SDW access mode for the segment in the supervisor's address space. The 
list can contain any combination of read, write, execute, and privileged. 
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acl 

is an ACL entry placed in the branch of the segment. Only segments placed in 
the hierarchy (via "path_name") can have ACL entries. The format of the acl 
arguments is "<access> Person_id.Project_id.tag", where Person.Project.tag must 
include all three components. 

bit_count 

is a number specifying a bit count to be associated with the segment, 
cache 

is either yes or no. It indicates whether or not to override the default 
encacheability of the segment. If you don't give this keyword, the following 
defaults are used: if you specify the per_process keyword as yes, then cache is 
yes; if you specify the init_seg or temp_seg keywords as yes or specify write 
access under the access keyword, then cache is no; otherwise cache is yes. 

cur_length 

is a number specifying the number of words to be allocated to the segment (for 
unpaged segments and segments loaded in collectionl). If this segment is a 
collectionl segment that is to be paged, cur_length is its length while unpaged. 

delete_at_shutdown 

is either yes or no. It indicates whether or not to return the pages of the 
segment to the appropriate free pool at shutdown time. 

init_seg 

is either yes or no. It indicates whether or not to delete the segment at the end 
of initialization. 

link_sect_wired 

is either yes or no. It indicates whether or not the linkage for the segment is to 
be combined in the supervisor's wired linkage section even though the segment 
itself might not be wired. 

max_length 

is a number specifying the number of pages to be allocated to this segment (for 
paged segments). The greater of max_length and cur_length (converted to pages) 
determines the size of the page table and the segment bound. 

paged 

is either yes or no. It indicates whether or not the segment is to be constructed 
as a paged segment. 

path_name 

specifies that the segment is to be placed in the hierarchy. The value of the 
argument is the pathname of the directory in which the segment is placed. This 
keyword is required for segments in collections. If you choose this keyword, all 
names listed for the segment are added to the version in the hierarchy. If an 
object segment is to be placed in the hierarchy, define it with the object 
keyword, so that the whole segment appears rather than just the text section. 
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per_process 

either yes or no. Indicates whether or not to suppress cx)pying of the SDW for 
this segment at process-creation time. 

ringbrack 

is 1, 2, or 3 numbers, separated by commas, to be interpreted as the ring 
brackets to be placed in the branch for segments that are to go in the hierarchy. 
Default ring brackets are (0,0,0). Rules for assigning ring brackets are described 
in the set_rin&_brackets command, 

sys_id 

specifies an external name in this segment identifying a location that is set to the 
eight-character system identifier (see -sys_id). This normally appears only for 
BCE/Multics system tapes and identifies the symbol active_all_rings_data$system_id. 

temp_seg 

either yes or no. Indicates whether or not to delete the segment at the end of 
the collection in which it was loaded. 

vers_id 

specifies an external name in this segment identifying a location that is set to the 
eight-character version identifier (see -vers_id). This normally appears only for 
BCE/Multics system tapes and identifies the symbol active_all_rings_data$version_id. 

wired 

either yes or no. Indicates whether or not the pages of the segment are to be 
wired. 

OPERATION 

The generate_mst command works by reading the header segments and performing one 
of the following: 

1. If the word found is an initial keyword, the information about the specified 
segment (i.e., all information up to the next end keyword) is gathered together 
and written on the system tape followed by the data for the segment itself. 

2. If the keyword is collection, a special mark is written on the tape indicating the 
end of the specified collection. 

3. If the keyword is fini, the tape is closed out and dismounted. 

For segments that are placed on tape (i.e., segments specified with an initial keyword), 
the first argument to the initial keyword is the name used when searching for the 
actual segment to be placed on tape. All subsequent arguments are treated as 
secondary names, and although they are placed on the tape in the preface area for 
each segment they are not used by the generator. 
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HARDCORE PROFILING 

If hardcore programs are compiled with the -profile or -long_profile options, it is 
possible to profile the behavior of the supervisor (see the -hardcore control argument 
to the profile command). 

There are several common pitfalls encountered in hardcore profiling. The size of the 
supervisor linkage segments must be increased to contain the additional static data 
generated by the profiling code. You can determine the required sizes from the 
loading summary information following collection two in the output file from 
checlL_mst The supervisor linkage segments are as_linkage ("active supervisor"), 
aijinkage ("active initialization"), wsjinkage ("wired supervisor"), and wijinkage 
("wired initialization"). They are defined near the beginning of the standard header. 
Unless you remove the init_seg and temp_seg keywords from initialization programs 
and their linkage sections, it is not possible to profile supervisor initialization programs 
(because the profiling information would otherwise be discarded as the system finished 
initialization), but this is rarely a problem. 

If wired code is to be profiled and you use -long^profile, the hcs__ gate and its 
linkage section must be wired because they are referenced by the virtual CPU time 
and paging calculation operators; this is not necessary if you use only -profile. If 
profiling a procedure that is specified as wired in the header but whose linkage 
section is specified as unwired, change the linkage section to be wired. 

Interrupt side code can be meaningfully profiled only with -profile, not with 
-long^profile, because interrupt code is not run in any particular process, and 
therefore the virtual CPU time calculation (which is per process) returns random 
results. This may lead to overflow faults while running on the PRDS. Because 
-profile does not require these calculations, you can use it with interrupt code. 

NOTES 

The procedures that generate the system tape must first find the necessary segments to 
place on the system tape and put them there in a manner that can later be read by« 
BCE and the initializing programs themselves. The system tape generating procedures 
find this information by scanning a header segment that contains names of programs 
and databases to be placed on the tape, along with other control information about 
the segments. 

There is a set of search rules specifying which directories are to be searched and the 
search order when looking for the specified segments. These rules can be contained in 
a segment, or you can use default rules. If you use no search segment, only the 
directory >idd>hardcore>execution is searched for the programs to be placed on the 
tape. 
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The standard system tape header used to generate the BCE/Multics system tape is 
« located in the segment >ldd>hardcore>info>hardcore.header. The standard headers 
contain many examples of valid header syntax. When you modify a header, first, if 
possible, locate an example of the modification elsewhere in the header since the 
semantics of the header are complicated. 

This command assumes the name of the header segment is path.header, where path is 
the path given. The output listing is placed in a segment path.list in your working 
directory. 

The search file must contain a list of directories to be searched, one directory name 
per line. A blank line signifies your working directory. 



Name: get_flagbox 
SYNTAX AS A COMMAND 
get_f1agbox f 1agbox_var iable 
SYNTAX AS AN ACTIVE FUNCTION 
Cget_flagbox f lagbox_variab1e] 
FUNCTION 

returns the value of a specified flag in the BCE/Multics communication area. 

ARGUMENTS 

flagbox_variable 

is one of the valid f lagbox variables listed below. 

bce_conmiand conmiand 

a conmiand to be invoked by BCE when it reaches a command level. This 
command is set so that if the system crashes, the command is automatically 
executed. See the Multics System Maintenance Procedures manual (AM81). 

kejrword 

can be either a number from 1 to 36 or the corresponding name of one of 
the f lagbox flags as given below. The names of the f lagbox flags are: 
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ACCESS REQUIRED 

Privileged access to phcs_ is required to use this command. 
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Name: get uid with lastname 

SYNTAX AS A COMMAND 
get_u i d_wi th_l astname name 
FUNCTION 

is used by the ison command in the master.ec. It searches the URF for all users with 
a given last name, and prints their full names and their assigned Person_ids. This 
information is useful in suggesting, or in predicting what the system will suggest as, a 
Person_id for a new user who has the same last name as one or more users already 
registered. 

ARGUMENTS 

name 

is the last name of a prospective new user. 

NOTES 

This command prints a series of lines of the form: 

User_id for "Lastname, Firstname I." is "Person_id" 
followed by: 

Number of users with lastname "Lastname" is N. 
ACCESS REQUIRED 

Use of this command requires read access on the system URF located at 
>udd>sa>a>urf. 
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Name: he ^pf^meters 

SYNTAX AS A COMMAND 
hc_pf_meters {-control_args} 
FUNCTION 

prints system-wide statistics concerning page faults taken on hardcore segments, 
including those taken on ring-O stacks. 

CONTROL ARGUMENTS 

-first N, -ft N 

causes the output to be sorted in descending order by number of page faults. 
Only the first N segments in this sequence are printed. 

-report 

prints data accumulated since the last invocation of the command with -reset or 
-report_reset, or since the last bootload (if the command has not been invoked 
with -reset or -report_reset). This is the default 

-report_reset, -rr 

generates a report and then performs the reset operation. 

-reset, -rs 

resets the metering interval for the invoking process. Does not print the report 
unless -report is specified. 

-sort 

causes the output to be sorted in descending order by number of page faults. If 
not given, the output is sorted in ascending order by primary segment name. 

ACCESS REQUIRED 

This command requires access to phcs_. 
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EXAMPLES 

See Appendix A for a representation of the configuration deck used to create the 
system from which the sample was taken. 

hc_pf_meters -first 20 



Total metering time 0:15:23 
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Name: hp delete, hpdl 

SYNTAX AS A COMMAND 
hpdl path 

FUNCTION 

deletes segments or directories (including their inferior directories, segments, and links 
(if accessible)) which cannot be deleted by the delete or delete_dir commands due to 
connection failures or other problems resulting from volume deregistration or the 
failure of emergency shutdown. 
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ARGUMENTS 
path 

is the pathname of the segment or directory to be deleted. The star convention 
may not be used. 

ACCESS REQUIRED 

The hp_delete command requires access to the highly-privileged hphcs_ gate. Access to 
the system_privilege_ gate is required as well. All discretionary (ACL) and nondiscretionary 
(AIM) access control is observed by this command. The segment or directory to be 
deleted may, however, have a lower ring bracket than the user's current validation 
level. 

NOTES 

The deletion is not logged in the syserr log. 

The user is queried once before performing the deletion. 

Out-of -service directories may be deleted. 

The segment safety switch is ignored. 



Name: hp delete acl, hpda 

SYNTAX AS A COMMAND 

hpda {path} {User__ids} {-control_args} 

FUNCT/ON 

removes entries from the access control lists (ACLs) of segments, multisegment files, 
directories, and gates. This command operates on objects whose ring brackets prevent 
them from being operated on by the delete_acl command. 
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ARGUMENTS 
path 

is the pathname of a segment, multisegment file, directory, or gate. If it is -wd, 
-working_dir, or omitted, the working directory is assumed. If path is omitted, 
no User_id can be specified. The star convention can be used. 

User_ids 

are access control names that must be of the form Person_id.Project_id.tag. All 
ACL entries with matching names are deleted. (For a description of the matching 
strategy, refer to the Multics Programmer's Reference Manual, Order No. 
AG91.) If no User_id is given, the user's Person_id and current Project_id are 
assumed. 

CONTROL ARGUMENTS 

-all, -a 

causes the entire ACL to be deleted with the exception of an entry for 
*.SysDaemon.*. 

-brief, -bf 

suppresses the message "User name not on ACL." 
-directory, -dr 

specifies that only directories are affected. The default is segments, multisegment 
files, directories, and gates. 

-segment, -sm 

specifies that only segments, multisegment files, and gates are affected. 
ACCESS REQUIRED 

The user needs modify permission on the containing directory. The system administrator 
needs access to the highly privileged gate hphcs_. 

NOTES 

If the hp_delete_acl command is invoked with no arguments, it deletes the entry for 
the user's Person_id and current Projeci_id on the ACL of the working directory. 

An ACL entry for *.SysDaemon can be deleted by specifying either *.SysDaemon.* or 
♦.SysDaemon. The user should be aware that in deleting access to the SysDaemon 
project he prevents Backup.SysDaemon.* from saving the segment or directory 
(including the hierarchy inferior to the directory) on tape, Dumper.SysDaemon.* from 
reloading it, and Retriever.SysDaemon.* from retrieving it. 
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EXAMPLES 

hp_del ete_acl news .Faculty. Jones 

deletes from the ACL of news all entries with Projectjd Faculty and the entry for 
Jones.*.*. 

hpda beta.** . . 

deletes from the ACL of every segment, multisegment file, directory, and gates (in the 
working directory) whose en try name has a first component of beta all entries except 
the one for *.SysDaemon.*. 

hpda beta.** . . -sm 

deletes from the ACL of only all segments, and multisegment files, and gates (in the 
working directory) whose entryname has a first component of beta all entries except 
the one for *.SysDaemon.*. 



Name: hp delete vtoce 

SYNTAX AS A COMMAND 

hp__del ete_vtoce pvname vtoc_index {-contro1_args} 
FUNCTION 

deletes a specified Volume Table of Contents Entry (VT(X)E). You can use it when 
cleaning up after a sweep_pv to get rid of orphans, or whenever you want a forward 
connection failure. 

ARGUMENTS 

pvname 

is the name of the physical volume on which the VTOCE to be expunged exists. 
vtoc_index 

is the index (in octal) of the VTOCE to be expunged. 
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CONTROL ARGUMENTS 
-brief, -bf 

suppresses the message announcing the deletion of the VTOCE, which is only 
printed if no questions are asked. 

-clear 

uses the privileged entry that sets an entire VTOCE to zero, rather than deleting 
it. Give -clear only when a VTOCE contains invalid information that may cause 
problems (reused addresses, crashes, etc.) if you delete it as usual, since it leaves 
the volume on which the VTOCE existed in an inconsistent state. Salvage such 
volume with the volume salvager after you have deleted all the seriously 
inconsistent VTOCEs. E>on't use this control argument to delete a reverse 
connection failure VTOCE (an ordinary orphan). 

-force, -fc 

forces the deletion of the VTOCE if it is an orphan, with no intervening 
questions; if it is not, you must supply also -no_check to suppress all questions. 

-no_check, -nch 

suppresses the check made to see whether or not the VTOCE is an orphan; if it 
is not, deleting it causes a forward connection failure in its parent directory. 

-query, -qy 

always queries whether or not to delete the VTOCE, even if it is an orphan. 
ACCESS REQUIRED 

You require access to the phcs_ and hphcs_ gales. 
NOTES 

You cannot use this command to delete the VTOCE of an active segment. The default 
is to check whether the VTOCE is an orphan, and delete it if it is, or ask whether 
to delete it if is not. 
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Name: hp set acl, hpsa 

SYNTAX AS A COMMAND 

hpsa path model User__icn ... modeN {User_idN} {-control_args} 
FUNCTION 

manipulates the access control lists (ACLs) of segments, multisegment files, directories, 
and gates. This command operates on objects whose ring brackets prevent them from 
being operated on by the set_acl command. 

ARGUMENTS 

path 

is the pathname of a segment, multisegment file, directory, or gate. If it is -wd 
or -working_dir, the working directory is assumed. The star convention can be 
used and applies to either segments and multisegment files or directories, 
depending on the type of mode specified in model. 

model 

is a valid access mode. For segments, multisegment files, or gates, any or all of 
the letters rew; for directories, any or all of the letters sma with the requirement 
that if modify is present, status must also be present Use null, "n" or "" to 
specify null access. 

User_idi 

is an access control name that must be of the form Person_id.Project_id.tag. All 
ACL entries with matching names receive the mode modei. (For a description of 
the matching strategy, see the Multics Programmer's Reference Manual, Order 
No. AG91.) If no match is found and all three components are present, an entry 
is added to the ACL. If the last mode_i has no User_id following it, the 
Person_id of the user and current Project_id are assumed. 

CONTROL ARGUMENTS 

(either control argument is used to resolve an ambiguous choice between segments 
and directories that occurs only when modei is null and the star convention is 
used in path): 

-directory, -dr 

specifies that only directories are affected. 

-segment, -sm 

specifies that only segments and multisegment files are affected. This is the 
default 
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ACCESS REQUIRED 

To use this command, a system administrator must have access to the highly privileged 
gate hphcs_. 

EXAMPLES 

hp_set_acl *.pll rew * 

adds to the ACL of every segment in the working directory that has a two-component 
name with a second component of pU an entry with mode rew to *.*> (everyone) if 
that entry does not exist; otherwise it changes the mode of the *.*.* entry to rew. 

hpsa -wd sm Jones . Facul ty 

adds to the ACL of the working directory an entry with mode sm for Jones.Faculty.* 
if that entry does not exist; otherwise it changes the mode of the Jones.Faculty.* entry 
to sm. 

hpsa alpha. basic rew .Faculty, r Jones.Faculty. 

changes the mode of every entry on the ACL of alpha. basic with a middle component 
of Faculty to rew, then changes the mode of every entry that starts with Jones.Faculty 
to read. 

hpsa >sll>hphcs_ re Jones. Work 
adds to the ACL of hphcs_ an entry with mode re for Jones. Work. 



Name: hpset dir ring brackets, hpdsrb 

SYNTAX AS A COMMAND 
hpdrsb path {opt i ona l_args} 
FUNCTION 

modifies the ring brackets of any directory, including directories whose ring brackets 
are 0,0. This command operates on directories whose ring brackets prevent them from 
being operated on by the set_dir_ring_brackets command. 

ARGUMENTS 

path 

is the relative or absolute pathname of the directory whose ring brackets are to 
be modified. 
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optional_args 
rbl 

is the number to be used as the first ring bracket of the directory. See 
"Notes" below. 

rb2 

is the number to be used as the second ring bracket of the directory. See 
"Notes" below. 

ACCESS REQUIRED 

To use this command, a system administrator must have access to the highly privileged 
gate hphcs_. 

NOTES 

If rb2 is omitted, the ring bracket is set to rbl. If rbl and rb2 are omitted, they are 
set to the user's current validation level. The ring brackets must be in the allowable 
range 0 through 7 and must have the ordering: 

rbl is less than or equal to rb2 



Name: hpset ring brackets, hpsrb 

SYNTAX AS A COMMAND 
hpsrb path {optional__args} 
FUNCT/ON 

modifies the ring brackets of any segment, including segments whose ring brackets are 
0,0,0. This command operates on objects whose ring brackets prevent them from being 
operated on by the set_ring_brackets command. 

ARGUMENTS 

path 

is the relative or absolute pathname of the segment whose ring brackets are to be 
modified. 

rbl 

is the number to be used as the first ring bracket of the segment See "Notes" 
below. 
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rb2 

is the number to be used as the second ring bracket of the segment. See "Notes" 
below. 

rb3 

is the number to be used as the third ring bracket of the segment See "Notes" 
below. 

ACCESS REQUIRED 

To use this command, a system administrator must have access to the highyl privileged 
gate hphcs_. 

NOTES 

If rb3 is omitted, the third ring bracket is set to rb2. If rb2 and rb3 are omitted, 
the ring brackets are set to rbl. If rbl, rb2, and rb3 are omitted, they are set to the 
user's current validation level. The ring brackets must be in the allowable range 0 
through 7 and must have the ordering: 

rbl is less than or equal to rb2 is less than or equal to rb3 



Name: idump 

SYNTAX AS A COMMAND 
idump path {-control_args} 

FUNCTION 

is the same as the backup_dump command, 
standalone command instead of being invoked 
Refer to the description of the backup_dump 



except that it assumes it is called as a 
by another hierarchy dumping command, 
command for details. 
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Name: iiihibit_pv 
SYNTAX AS A COMMAND 
inhibit_pv pvnaine {-control__arg} 
FUNCTION 

sets up for the evacuation of a physical volume and inhibits further segment creation 
on that volume. 

ARGUMENTS 

pvname 

is the name of a physical volume. 
CONTROL ARGUMENTS 
-off 

allows segment creation again on the named physical volume. 
ACCESS REQUIRED 
You need access to the h]dics_ gate. 
NOTES 

Attempting to inhibit a volume already inhibited or to disinhibit one not inhibited 
produces a diagnostic. 



Name: install 

SYNTAX AS A COMMAND 
install path {-control^args} 
FUNCTiON 

requests installation of a system control table. 

ARGUMENTS 

path 

is the relative or absolute pathname of the table to be installed. You must give 
the appropriate suffix (e.g., pdO. 
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CONTROL ARGUMENTS 

-all, -a 

installs all attributes. 

-attributes, -attr 

installs only nonsecurity-related attributes. (Default if you specify no control 
arguments) 

-authorization, -auth 

installs only security-related attributes. 

NOTES 

The request is transmitted to the system control process. This process validates the 
request, attempts to perform the installation, and sends a message indicating the success 
or failure of the installation. 

This command reports PDT parameters that exceed limits specified for the project in 
the SAT, but it allows the PDT to be installed. If the SAT limits are not 
subsequently raised, they are enforced at login time and a message indicating that is 
logged. This is done for the initial ring, max ring, grace time, and pdir quota 
parameters. 

A project administrator can install a PDT only; a system administrator can also install 
a number of additional tables. 

EXAMPLES 

install Alpha.pdt -auth 

installs the security-related attributes in the PDT named alpha.pdt found in the project 
administrator's working directory. 

install >udd>Demo>Demo.pdt 
installs the PDT named demo.pdt found in the Demo project directory. 

A message like this is sent to the project administrator when the installation has been 
completed: 

From In! tial izer .SysDaemon.z (install) 1321.0: 
installed Demo.pdt for Renoi r .Demo.a. 
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Name: instr^^peed 
SYNTAX AS A COMMAND 
i nstr_speed 
FUNCTION 

measures the speed of a processor by timing a series of code sequences. 
NOTES 

The code sequences are chosen to test the more common and important sequences of 
instruction as well as to get a general idea of the limiting speed Uiat can be expected. 
It is better if you select a processor with the s&t_proc_required conmiand before 
running timing tests. 

Code sequences that take longer than expected, probably due to interrupt or fault 
action, are factored out and not counted. 



Name: intem^t^jmeters, intm 
SYNTAX AS A COMMAND 
Intm {-control^args} 
FUNCTION 

prints out metering information for input/output multiplexer (lOM) channel interrupts. 
CONTROL ARGUMENTS 
-channel N 

prints out only interrupt metering information for !OM channel N. 
-iom N 

prints out only interrupt metering information for those channels on IOM N. 

-report_reset, -rr 

generates a full report and then performs the reset operation. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 

the last call with --rs specified. Having never given -rs in a process is equivalent 

to having specified it at system initialization time. 

-total, -tt 

prints out only the total IOM and non-IOM interrupt metering information. 
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ACCESS REQUI RED 

You need access to phcs_ or metering_gate_. 
NOTES 

If you give intm without control arguments, it prints a full report 

The following are brief descriptions of the metering information printed out by intm. 



Int 

is the number of interrupts that occurred. 
Avg Time 

is the average time (in milliseconds) needed to handle each interrupt 
% CPU 

is the percentage of total CPU time needed to handle the interrupts. 
Name 

is the name of the device on the channel. 
The following are descriptions of the totals printed by intm. 
Chan 

is the total of all lOM channel interrupts. The times printed are based on the 
total time spent in the per-channel interrupt handlers. 

Other 

is the total of all lOM interrupts. Each lOM interrupt may cause the handling of 
several channel interrupts. The times printed include only that time in the 
common interrupt path and exclude time spent in the per-channel handlers. 

Total 

is the total of all interrupts handled by the system. 
EXAMPLES 

The following is an example of the information printed when you invoke intm without 
control arguments. (See Appendix A for a representation of the configuration deck 
used to create the system from which the samples were taken.) 
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Total metering time 0:15:25 
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37. 


278 


0.749 


0.00 


dskg 


B 
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Chan 
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Ovhd 
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1.10 




Total 


224799 


1.735 


8.43 
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Name: io_error ^summary 

SYNTAX AS A COMMAND 
io_error_summary {-control_args} 
FUNCTION 

scans the syserr log and summarizes I/O errors in a brief report 
CONTROL ARGUMENTS 
-cylinders, -cyl 

separates the disk device error by cylinder and head. Only disk control syserr 
messages can be separated. 

-detailed_status, -dtst 

displays detailed status if available. 

-device STRs, -dv STRs 

reports information for the device(s) named, where STRs are device types C'prt") 
or device names ("prtb"). 

-for T 

computes the ending time from the starting time, where T is a relative time (such 
as "1 hour"). 

-from DT, -fm DT 

starts scanning the log at the date/time given. 

-hex_detailed_status, -hxdtst 

displays detailed status in hexidecimal if available. 

io_command, -ioc 

displays the I/O conmiand that was being executed when the abnormal status 
occurred. The conmiand is displayed in octal, in parenthesis, prior to the 
interpreted status. 

-status status_list, -st status_list 

reports information for the lOM status listed, where status_list is the lOM major 
and substatus ("0310" or "4310"). 

-tape_data_bit_in_error, -tdbie 

displays the data bit(s) in the detailed status that were in error. 

-to DT 

stops scanning the log at the date/time given. 
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ACCESS REQUIRED 

You need read permission on the log segments and status permission on their 
containing directories. 

NOTES 

If you give no -from, the scan starts with the earliest message in the syserr log. You 
can specify the ending time by using -for or -to, but not both. If you omit both, 
the scan terminates with the last message in the log. All dates and times must be in 
a format acceptable to convert_date_to_binary_ (see the Multics Subroutines and 110 
Modules manual, AG93). 



Name: iod_command 

SYNTAX AS A COMMAND 

i od_command i o_daemon_coinmand {args} 

FUNCTION 

permits execution of I/O daemon conwnands from within admin exec_coms invoked by 
the I/O daemon x conmiand. 

ARGUMENTS 

io_daemon_command 

is the I/O daemon command to be executed. 

args 

are any arguments needed to implement the specified command. 
NOTES 

You canH issue the go command using iod_command. 
EXAMPLES 

i od_command defer_time pica_10 30 

can be used within an I/O daemon admin exec.com to set the auto defer time of the 
pica^lO minor device of the current I/O daemon driver to 30 minutes. 
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Name: iod tables compiler 

SYNTAX AS A COMMAND 
i od__tab 1 es_comp i 1 er path 
FUNCTION 

is the translator for the I/O daemon tables source language. Source segments to be 
translated by iod_tables_compiler must have a name ending with the suffix iodt. The 
name of an object segment produced by iod_tables_compiler is the same as that of 
the corresponding source segment with the iodt suffix removed. The object segment is 
placed in your working directory. 
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ARGUMENTS 
path 

is the relative or absolute pathname of the source segment to be translated. 



Name: iod val 

SYNTAX AS AN ACT/VE FUNCTION 

[iod__val key] 

FUNCTION 

supplies several preset driver parameters to be used in driver admin exec_coms. Site 
administrators use the iod_val active function in conjunction with the driver x 
command to set up and modify these exec_coms. 

ARGUMENTS 

key 

is a character string parameter name associated with the value to be returned. 
The key, defined during initialization of the given driver, may be one of the 
following: 

For all standard drivers: 
device 

the name of the major device that the driver is running. 
station_id 

the name of the station_id that the driver is running (equivalent to the major 
device). The default is the name of the major device if the station is not a 
remote device, 

request_type 

the name of the request type that is being run on the driver, 
channel 

the name of the iom or tty channel of the driver. 
<minor device> 

the name of the request type that is being processed on the minor device. 
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rqt_string 

a string of request type names, separated by spaces, of all (printer, punch, 
etc) request types the driver can process. This key is equivalent to the 
request_type key if the driver is running only one minor device. 

For remote drivers: 

request_type 

the request type for a single printer device, if present 
pun_rqt 

the request type for a single punch device, if present 

NOTES 

If a key is given that has not been defined, the string "undefined " is returned. 



Name: is he user 

SYNTAX AS AN ACTIVE FUNCTION 
[is_he_user Person_id] 
FUNCTION 

function returns "true" if its argument is the name of a user in the URF hash table 
(urf.ht) in the current working directory; it returns "false" otherwise. 

NOTES 

The function is used in the master.ec segment to detect errors in the input arguments. 



Name: is legal proj 

SYNTAX AS AN ACTIVE FUNCTION 
[i s_ legal __proj Project_id] 
FUNCTION 

returns "true" if its argument is listed in the current SAT copy (smf.cur.sat) in the 
user's working directory, or it returns "false" otherwise. 
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NOTES 

This function is used in the master.ec segment to detect errors in the input arguments. 



Name: link meters 

SYNTAX AS A COMMAND 
link_meters {-control__arg} 
FUNCTION 

prints out per-process information regarding use of the Multics linker. The statistics 
are obtained from the Process Descriptor Segment (PDS) of the process. System-wide 
linkage information can be obtained with the system_link_meters command (described 
later in this section). 

CONTROL ARGUMENTS 

-report_reset, -rr 

generates a full report and then performs the reset operation. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 
the last call with -reset specified. If -reset has never been given in a process, it 
is equivalent to having been specified at process initialization time. 

ACCESS REQUIRED 

This command requires access to phcs_ or metering_gate_. 
NOTES 

If the link_meters command is given with no control argument, it prints a full report 

The following are brief descriptions of the variables printed by the link_meters 
command. 

slot 

is a time slot into which the calls to the linker are broken down. The four slots 
are for calls completed in less than 25 milliseconds, calls completed in between 25 
and 50 ms, calls completed in between 50 and 75 ms, and calls completed in 
more than 75 ms. 
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calls 

is the number of calls to the linker that are completed in each time slot and the 
total number of calls made to the linker by the process. 

avg time 

is the average time (in milliseconds) to completion for a call in each slot and the 
average time to completion for all calls to the linker made by the process. 

avg pf 

is the average number of page faults for a call in each slot and the average 
number of page faults for all calls made by the process. 

tot time 

is the total virtual time (in seconds) taken by calls in each slot and the total 
virtual time spent in the linker by the process. It equals calls times average time. 

% time 

is the percentage of total linker time for the process that was taken by calls in 
each slot and the percentage taken by all calls. 

EXAMPLES 

The following is an example of the information printed when the link_meters 
command is invoked with no control argument. (See Appendix A for a description of 
the configuration deck used to create the system from which the metering sample was 
taken.) 



L i nkage 


Meters: 










slot 


ca 1 1 s 


avg time 


avg pf 


tot time 


% t ime 


<25 


320 


6.673 


0.3 


2.135 


76.1 


25-50 


14 


28.432 


2.1 


0.398 


14,2 


50-75 


0 


0.000 


0.0 


0.000 


0.0 


>75 


1 


272.756 


10.0 


0.273 


9.7 


Total 


335 


8.377 


0,h 


2.806 
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Name: list_as__requests 
SYNTAX AS A COMMAND 
1 i st__as_requests 
FUNCTION 

displays any answering service requests currently pending in the answering service 
request queue message segment (>scl>as__requestms). 

ACCESS REQUIRED 

You must have o access to as.requestms to display your own requests. You must have 
r access to as.requestms to display requests 'entered by others. 



Name: list__delegated_„projects 

SYNTAX AS A COMMAND 

1 i st_delegated__projects sat__path {^roject_id} 
FUNCTION 

is used by the who^delg command in master.ec to list the administrator(s> of a given 
delegated project, or to list all delegated projects, with their administrators. 

ARGUMENTS 

sat_path 

is the pathname of the SAT to be searched for delegated projects. If the 
entryname portion of sat_path is given without a suffix of sat, the suffix is 
added (unless the entryname portion is simply ''sat**). 

Projecl_id 

is the Project_id of the delegated project whose administrators are to be listed. If 
this argument is not given, all delegated projects are listed. 
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NOTES 

The output from this command is of the form 

Project Administrator 
Project_id] Adminl 

Admi n2 

Adml n3 

Project_id2 Adminl 
Admi n2 



Name: list extra^personids 

SYNTAX AS A COMMAND 
I 1 i st_extra__personids 
FUNCTION 

lists Person_ids that are registered in the PNT but do not exist in any PDT. 
Personjds in a PDT but not in the PNT are also listed. 

NOTES 

This cx>mmand is useful for checking the consistency of system tables and listing those 
Person_ids that can be removed from the PNT to compress it (See remove_user for 
more information.) 

The command also references the SAT in >scl and the PDTs for all valid projects in 
>scl>pdt 

First, the PDTs are scanned, and a list of users missing from the PNT is printed; this 
list is probably due to errors by project or accounting administrators. Then, a list of 
* Person_ids in the PNT but not in the PDTs is printed. 

This command is expensive. Therefore run it on absentee or at least using file.output 
(see the Multics Commands and Active Functions manual, AG92) so that the results 
can be saved. 
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Name: list_mst 

SYNTAX AS A COMMAND 
llst__mst reel_»d {names} 
FUNCTION 

lists segments on a system tape (a BCE/Multics bootload tape). 

ARGUMENTS 
reel_id 

is the reel identification number of the tape to be listed. This reel identification 
number, which is site dependent, can be up to 32 characters long, and can include 
a density specification to indicate the density of the tape being written; as in 
"060341.den=1600". 

names 

are names of segments to be listed. If you give no names, all the segments on 
the tape are listed. You can use the star convention. 

NOTES 

A summary line, giving the length of each segment and its primary name, is printed 
out for each segment listed. A special name is printed out for segments written with 
the first_name keyword of the generate_mst command because the proper name of 
such segments does not appear on the tape. A diagnostic is issued if you provide 
names that match no segments on the tape. 



Name: list^partitions 

SYNTAX AS A COMMAND 
n st_parti t ions pvname 
FUNCT/ON 

lists the locations and sizes of all the partitions on a specified physical volume (see 
clear_partiticn and dump^partition). 

ARGUMENTS 

pvname 

is the name of the physical volume whose partitions are to be listed. 
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NOTES ON OUTPUT FORMAT 

The output consists of a header, which lists the physical and logical volume names, the 
PVID and LVID, the size of the volume in pages, the size of the VTOC in both 
pages and VTOCEs, the size of the paging region, and the number of partitions. It is 
followed by a table listing the name, first record, and size of all partitions and other 
regions on the volume. All numbers in the table are given in both decimal and octal 
(in parentheses), and all other numbers in the output are decimal. 



Name: list__proc__reqiiired 

SYNTAX AS A COMMAND 

1 i st__proc__requi red {-control_arg} 

SYNTAX AS AN ACTIVE FUNCTION 

[1 i st_proc_requi red {control_arg}] 

FUNCTION 

determines the group of CPUs on which the invoking process can be run or the 
default group of CPUs for all processes that have not requested specific CPUs. 

CONTROL ARGUMENTS 

-priv 

indicates that this command applies to the default group of CPUs for processes 
that have not requested specific CPUs. If omitted, this command applies to the 
group of CPUs for the invoking process only. 
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ACCESS REQUIRED 

This command requires access to phcs_ or metering gate . 

NOTES 

When invoked as a command without the -priv control argument, list_proc_required 
indicates that the set of CPUs needed for this process is the system default by 
printing "(default)" following the list of CPUs. This information is not provided when 
list_proc_required is invoked as an active function. If invoked as an active function, 
it returns a string of CPU tags that represent the group of CPUs requested (e.g., 
"ABCF"). 

This command prints the list of CPUs required as an uppercase string. If invoked as 
an active function, it prints the returned list of CPU tags in uppercase. 

EXAMPLES 

This command is most useful when used in conjunction with the set_proc_required 
command to verify that the restriction specified in an earlier invocation of 
set_proc_required is still in operation. The effect of set_proc_required can be canceled 
by the system because of dynamic reconfiguration without notification to the process 
affected. If the following set of commands are input 

set_proc_requi red A 

{other commands} 

1 i st__proc__requi red 

an output of "A" from list_proc_required indicates that all commands between the 
set_proc_required and the list_proc_required were run entirely on CPU a. Any other 
output indicates that the effect of the set_proc_required has been canceled due to 
dynamic reconfiguration. 



Name; list vols 

SYNTAX AS A COMMAND 
list_vols {lv_name} {-control_args} 
SYNTAX AS AN ACTIVE FUNCTION 
[list_vo1s {Iv^name} {-control_args}] 
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FUNCTION 

prints information about currently-mounted physical or logical volumes. Several of the 
items printed by list_vols can also be obtained as return values by invoking lisl_vols 
as an active function. 

ARGUMENTS 

lv_names 

prints information about the logical volume lv_name. This is the default if a 
name is given without -Iv or -pv preceding it. 

CONTROL ARGUMENTS 

-grand_total, -gtt 

prints a single number about the total records left or records used on the system. 
This is used in conjunction with the -rec_used control argument, or if no other 
control argument is given, -rec_left is assumed. This allows a command line 
equivalent of active function usage as: [list_vols -rec_left] or [list_vols 
-rec_used] where -rec_left is also the default. 

-Iv name(s) 

prints information about the logical volume(s) named. A single name or several 
names, separated by space, can be given. 

-pv name 

prints information about only the physical volume named, 
-records, -rec 

prints only the number of records on the specified volume(s), exclusive of records 
occupied by partitions and the volume table of contents (VTOC). This is one of 
the items that can be obtained as an active function return value. 

-records_left, -rec_left 

prints only the number of records on the specified volume(s) that are currently 
unused and are available to hold the pages of segments and directories. This is 
one of the items that can be obtained as an active function return value. (This is 
the default) 

-records_used, -rec_used 

prints the number of records on the specified volume(s) that are used. This can 
be obtained as an active ftmction value. 

-totals, -tt 

does not print information for individual physical volumes but rather totals and 
prints for each logical volume. 

ACCESS REQUIRED 

This command requires access to phcs_ or metering_gate_ as well as mdc_. 
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NOTES 

If no volume name is given, the list_vols command prints information about all 
mounted logical volumes. 

If physical volume information is being printed, there may be up to two flags printed 

immediately to the right of the drive name. The flags are "X" (if a drive is 
inoperative) and "I" (if a drive is inhibited for segment creation). 

If a physical volume information is being printed, the average segment size, to the 
nearest record, is printed per physical volume. 

If either logical volume or physical volume information is being printed, the 
percentages used or left for Records and VTOCEs is printed. 

If list_vols is used as an active function, either the -records or the -records_left 
control argument must be given. 

If the -totals argument is given together with the name of a logical volume, a single 
line containing totals information for that logical volume is printed. 

If physical volume information is being printed (-totals not given), the output lines 
contain the following items: 

Drive flag Records Left VTOCEs Left PV Name PB/PD LV Name 

If logical volume information is being printed (-totals given), the output lines contain 
the following items: 

Records Left VTOCEs Left PB/PD Lv Name 
The following are brief descriptions of the above variables. 
Drive 

is the name of the drive on which the physical volume is mounted. 

flag 

is the letter "X" if the drive is inoperative. 
Records 

is the number of records not occupied by partitions or the VTOC, and therefore 
usable for the pages of segments and entries. 

Uft 

is the number of records currently imused and therefore available for the pages 
of segments and directories. 

VTOCEs 

is the number of VTOC entries. 
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Uft 

is the number of unused VTOC directories. 

PV Name 

is the name of the physical volume. 

PB/PD 

contains "pb" if the logical volume is public, and "pd" if it has been designated 
as being available to hold the segm-ents in process directories. 

LV Name 

is the name of the logical volume. 

EXAMPLES 

The active function: 

[list_vols -records__l ef t root] 
returns the number of records left on the root logical volume. 
The command: 

list_vols -tt root 

prints the following totals for the root logical volume. 

Records Left VTOCEs Left PB/PD LV Name 
50267 ^026 20185 787^ pb root 

The following is an example of the information printed when the list_vols command is 
invoiced with no control arguments. (See Appendix A for a representation of the 
configuration deck used to create the system from which the metering samples was 
taken.) 
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Name: list volume registration, Ivr 

SYNTAX AS A COMMAND 
Ivr control args 
FUNCTION 

displays the registration information for a physical volume or a logical volume with all 
its physical volumes. 

CONTROL ARGUMENTS 

The "-physical_volume" or the "-logical_volume" control argument is required and 
must immediately follow the command name. (Only one may be supplied.) 

-physical_volume PV_NAME, -pv PV_NAME 

specifies that the registration information for the given physical volume is to be 
displayed. 

-logical.volume LV_NAME. -Iv LV_NAME 

specifies that the registration information for the given logical volume is to be 
displayed. 

-brief, -bf 

if given with the "-logical_volume" control argument, will specify that only the 
names of the physical volumes are to be displayed. No other information is 
given. This control argument is ignored when "-physical_volume" is specified. 

ACCESS REQUIRED 

The user of this command is required to have "re" access to the mdc_priv_ gate and 
"s" to >lv. 
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EXAMPLES 

-> Ivr -Iv root 
Ivname: root 
Ivid: 
publ ic: 

owner : 

m i n_access_c 1 ass : 
max_access_c 1 ass : 
acs_path: 

npv: 

pvname: rpv 

pvi d : 

ser i a1 : 

mode 1 : 

location: 

date registered: 

pvname: root2 

pv i d : 

ser i a) : 

mode 1 : 

location: 

date registered: 

-> Ivr -Iv root -bf 

rpv 
root3 



Name: loJad mpc 

SYNTAX AS A COMMAND 

load_mpc {mpc_name} {-control _args} 

FUNCTION 

loads ITRs or application firmware or both into MFCs. 



3l6itO420264l (! gwBcBjbbBBBBBB) 
yes 

Initial i zer . SysDaemon 
0:000000 0 

7:777777 (system_high) 
>lv>root.acs 

2 



516404202602 (IgwBcBjCBBBBBB) 

3M - 345666 

451 

dska 34 

02/05/84 1552.7 edt Sun 



520225300221 (IhBdhbDLbBBBBBB) 
unspec i f i ed 

501 

uni ni t i al i zed 

02/05/84 1554.1 edt Sun 
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ARGUMENTS 
mpc_name 

is the name of the MPC to be tested or reloaded or both. This name must 
appear on an mpc card in the config deck. If this argument is omitted, the 
-channel control argument must be given. 

CONTROL ARGUMENTS 

I -channel channel_name, chn channel_name 

specifies a channel name, where channel_name is of the form {iomtag} channel_no 
(for example, al4). The iomtag field must be the tag of a configured lOM and is 
required on multiple lOM systems. The channel_no field is an octal channel 
number. If this control argument is used, the mpc_name argument is optional. If 
both are used, the channel must be connected to the mpc specified. 

-itr 

loads only the ITRs; the standard firmware is not reloaded. 

-firm 

loads ony the standard firmware; ITRs are not run. 

-revision RV, -rev RV 

specifies which revision of the firmware is to be loaded, where RV is a 
2-character firmware revision code. If multiple revisions exist and this argument 
is omitted, you are queried as to which revision to load. 

-time, -tm 

prints timings for each program loaded into the MPC. 
-brief, -bf 

withholds printing of the names of the programs as they are run. 
I ACCESS REQUIRED 

I To use 'load_mpc, you must have access to the phcs gate. 
NOTES 

By default, this command suspends I/O on all devices connected to the selected MPC, 
resets the controller, runs all the known ITRs, reloads the standard firmware (including 
device routines for urmpc), and restores I/O on all devices connected to the 
controller. 

If any abnormal conditions occur, the program displays the status that occurred, and 
stops. I/O is left in a suspended state, because the MPC has been left in an unusable 
state. In order to return the controller to operation, it is necessary to restore the 
firmware, using either this command or TOLTS (documented in the Multics Online 
Test and Diagnostics Manual, Order No. AU77). 
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You can use load_mpc on disk MFCs only if they are fully cross barred. 

Firmware and ITR modules are found in the test and diagnostics (T&D) deckfile 
created by the load_tandd_library command (see the Multics Online Test and 
Diagnostics Reference Manual (AU77). 

This command informs the operator, through the main initializer console, of major 
events during conmiand execution; the events include suspending I/O, running ITRs, 
loading firmware, and resuming I/O (or leaving I/O suspended). 



Name: load ctl status 

SYNTAX AS A COMMAND 

load_ct l_status {group} {-control_args} 

FUNCTION 

prints the current status of the system load control groups, i.e., prints selected items 
from the system copy of the master group table (MOT). 

ARGUMENTS 

group 

prints only the header and the line for the group named; otherwise, prints one 
line for each group in the MGT. Each line gives the maximum number of 
primary load units; the current nimiber of primary load units; the current number 
of secondary load units; the group's current load, as a percentage of the total 
allowable system load; and, if the group has an absolute maximum, the total and 
maximum number of units. 

CONTROL ARGUMENTS 

-long, -Ig 

requests a long format header. 

-total, -tt 

requests that only a header be printed. 

Ai^-r r-c> 
'Ul CO 

If the priority scheduler is enabled, then each line gives, in addition, the interactive 
and absentee work class of the group, and the header contains two additional lines 
giving the defined work classes and their percentages, for the current shift 
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SYNTAX AS A COMMAND 

lock_mca 

FUNCTION 

locks (disables) input to all maintenance channel adapters (MCAs) from the console. 



Name: make_coiiimands 
SYNTAX AS A COMMAND 
make_commands path_name 

FUNCTION 

creates a Limited Service Subsystem (LSS) control segment from an ASCII input 
segment The control segment is referenced by the Limited Service System (LSS) when 
it is limiting the commands and percentage of CPU time of a user (see also the 
enter_lss command). 

The input segment consists of a series of statements. Each statement is composed of 
two parts. The first part is the name of the conmiand to be transformed; i.e., the 
command that is to be typed by the user in a limited system. If there is more than 
one name for the command, they should all be enclosed in parentheses and separated 
from each other by one or more blanks. The name field is terminated by a colon 
preceded by any number of blanks. 

The second part of each statement is the pathname (which may be a relative 
pathname) of the command to be executed when the user types one of the names in 
the first part If a relative pathname is used, it is relative to the current working 
directory. If only an entryname is given, the standard system search rules are applied. 
It is followed by any number of blanks and terminated by a semicolon. If the 
pathname is omitted (semicolon still required), it is assumed to be the same as the last 
name in the name field. 

The first and second parts of each statement may be separated from each other by 
any number of blanks or tabs. Newlines are ignored and are allowed anywhere. 
(Comments enclosed between and are allowed and are treated as blanbL 

If the first two statements have as their first part the names "ratio" and "interval*', 
respectively, the second parts of the two statements are assumed to be decimal integers 
to be assigned to the ratio and intervaljength variables of the LSS control segment 
Otherwise, the two variables are set to zero. 
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The ratio and interval variables control the amount of CPU time used by the process. 
The LSS forces the process to use no more than (interval/ratio) virtual CPU seconds 
in each (interval) real second(s) (see "Examples" below). If it attempts to do so, the 
process is rendered inactive for the remainder of the interval. 

ARGUMENTS 

path^name 

is the pathname of an ASCII input segment that has the name path_name.ct (The 
.ct suffix is assumed if it is not included.) The output segment has the same 
entryname as the input segment with the .ct suffix removed, and is placed in the 
working directory. 
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EXAMPLES 

A project administrator wants to create a limited command environment for a project 
consisting of student users. The first step is to create the segment 
>udd>Studepts>student_commands.ct, with the following contents: 

/* set the ratio and interval 

ratio: 60; 
interval: 120; 

/* def i ne the commands */ 

(list Is): >abc>spec i al $ 1 i St; 

logout: ; 

edit: bsys; 

Start: ; 

hold: ; 

(pr print) : ; 

Then, to convert this segment to an LSS control segment, type: 
make_commands stuclent_commands .ct 

The command then creates an output segment named student_commands, which can be 
put to use with the enter_lss command. 

In the above example, the ratio is set to 60, and the interval is set to 120, indicating 
that no more than 2 virtual CPU seconds are allowed per 120 real seconds. 

NOTES 

See the enter_lss command for additional information. 



Name: make volume labels 

SYNTAX AS A COMMAND 

make_vol ume_l abel s volume_spec {-control_args} 
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FUNCTION 

generates data for producing stickers to be attached to volumes (e.g., tape reels and 
disk packs). For each volume name specified, two labels are prepared. The first label 
contains the name of the resource, and the second label contains a three-character 
authentication code for the volume. Any number of volume names may be specified, 
including volume name series. 

ARGUMENTS 

volume_spec 

is either a single volume name, or the sequence "volume_namel -to volume_name2". 
When the second sequence is specified, both volume_namel and volume_name2 
must end with one or more digits. Label data will be produced for each volume 
in the sequence specified. Each volume name may be as long as 32 characters. A 
volume name may not contain spaces. 

CONTROL ARGUMENTS 

-auth_only 

specifies that labels containing the volume names are not to be generated. If this 
argument is specified, only authorization code labels are produced. The default is 
to produce both types of labels. 

-height N 

specifies that the labels on the stock to be used are N lines in height, measured 
from the first line of one label to the first line of the next label. The default 
for N is 9. The data produced assumes printing at six lines per inch. 

-name_only 

specifies that labels containing authorization codes are not to be generated. If this 
argument is specified, only volume name labels are produced. The default is to 
produce both types of labels. 

-output_swiich switchname, -osw switchname 

specifies the name of the I/O switch over which the label data is to be written. 

If this control argument is omitted, the data will be written over the I/O switch 
named "label_stream". 

-width N 

specifies that the labels on the stock to be used are N characters across. The 
default for N is 50. 
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NOTES 

Each sticker will contain data in a 5x5 format. Uppercase characters are distinguished 
from lowercase characters by additional underscoring. If the data in 5x5 format cannot 
be accommodated on the size sticker specified, a warning is printed, the data is 
truncated, and an indicator is appended to the label to show that the name has been 
truncated. However, all stickers always contain a line printed in normal characters, 
containing both the complete volume name and the authentication. 

If the sequence "volume_namel -to volume_name2" is specified, both volume names 
must contain numeric portions, and the rightmost numeric portion of volume-name2 
must not be numerically less than that of volume_namel. Labels are generated for 
each volume in the sequence. Only the rightmost numeric portion of the resource 
name is incremented. Leading zeroes are not generated in the significant numeric 
portion unless they are explicitly specified as part of volume_namel. 

The I/O switch on which the labels are to be written is assumed to be attached and 
opened for stream output before the command is invoked. (See the description of the 
io_call command in the Multics Commands and Active Functions manual. Order No. 
AG92, for information on attaching and detaching I/O switches.) 



Name: map355 

SYNTAX AS A COMMAND 

map355 pathname {-control_args} 

FUNCTION 

is used to assemble a program written in the FNP assembler language, map355. The 
command does not assemble the program directly. Instead, it prepares a GCOS job 
deck to perform the assembly and calls the GCOS Environment Simulator to do the 
work. 

ARGUMENTS 
pathname 

is the pathname of the source program to be assembled. The suffix of map355 
need not be given by the user; it is assumed. 

CONTROL ARGUMENTS 

-argument list, -ag list 

specifies a list of arguments to be passed to the GCOS Environment Simulator. 
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-check 

specifies that the compiler only perform a syntax check of the source. No object 
segment is created. 

-comdk 

creates a GCOS comdk segment. This segment contains a BCD version of the 
source program. It is created in the working directory with a suffix of comdk. 

-gcos_iist, -gels 

creates a GCOS listing segment in the working directory. This is a BCD version 
of the listing segment. It has a suffix of glisL 

-list, -Is 

creates a listing segment that documents the compilation. The listing is created in 
the working directory, and has a suffix of list. 

-macro_file path 

specifies the pathname of the macro file to be used for the assembly. If omitted, 
>ldd>comm>fnp>info>355_macros is used. 

-noconvert 

specifies that the input segment is a GCOS comdk, rather than an ASCII segment. 
If this control argument is used, the source segment must have a suffix of 
comdk. 

NOTES 

This command creates a series of segments for use by the GCOS simulator. Some are 
created in the working directory, some are created in the process directory, and some 
through links in the working directory to the process directory. These segments and 
links are normally deleted when the command terminates, leaving just the object 
segment, which has a suffix of objdk. 

Refer to the GCOS Environment Simulator manual. Order No. AN05, for more 
information on the use of the GCOS Environment Simulator. 

WARNING 

The map355 command creates links in the working directory to segments to be placed 
in the process directory. If the process terminates in the middle of a compilation 
(new_proc or a crash), these links will remain. This means that the next time the 
command is invoked, it will fail because the links point to a nonexistent directory. 
Even though the command fails, the bad links will be unlinked and subsequent 
invocations will work correctly. 
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LIST OF SEVERITY VALUES 

The map355 command sets the following severity values to be returned by the severity 
active function when the "map355" keyword is used: 

Value Meaning 

0 No error (or command not yet used) 

1 The assembly produced warning flags 

2 The objdk segment could not be created 



Name: mc trace, met 

SYNTAX AS A COMMAND 
met path {-control_args} 

FUNCTION 

gives a snapshot of machine conditions and history registers (resulting from hardware 
faults and interrupts) incurred while executing another Multics command or subroutine. 

ARGUMENTS 

path 

is the absolute or relative pathname of the segment that is to be traced. 
CONTROL ARGUMENTS 
-all 

captures machine conditions and history registers for every fault and interrupt that 
occurs in your process. This control argument cannot be used with -he or the 
path argument 

-brief, -bf 

suppresses printing the " — >" prompt 
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-buffer N, -buf N 

sets the machine condition trace buffer size to N, where N is a decimal integer 
value from 1 to 16, and represents the buffer size in units of 1024 words (IK). 
The default buffer size is 5K words. 

-he SEG 

captures machine conditions and history registers for faults and interrupts that 
occur in the hardcore segment SEG while your process is in execution. SEG can 
be a hardcore segment name or number. This control argument cannot be used 
with -all or the path argument. 

NOTES 

This command initiates the segment specified by the path argument, and creates the 
machine condition trace buffer in your process directory. The number of machine 
conditions and history register sets that can be stored is directly related to the size of 
the trace buffer. There is an approximate 8 to 1 ratio of machine conditions to 
history registers (e.g., in a 5K buffer there would be storage for 79 sets of machine 
conditions and 10 sets of history registers, allowing room for a trace buffer header). 
The trace buffer is temporarily "wired" (i.e., the segment remains in main storage and 
is not subject to removal by the dynamic paging mechanism). The hardcore snapshot 
or trace mechanism is then enabled and mc_trace goes into a request loop after 
printing " — >" as your prompt on the error_output switch. The valid user reponses 
while in this request loop are as follows: 

. prints out the command name "mc_trace" on the user_output switch. 

.q turns the hardcore snapshot mechanism off, unwires the machine condition buffer, 
and returns to Multics command level. 

..<command> calls the Multics command processor and executes <command> as a 
Multics command (e.g., ..who). 

.rpt n <command> calls the Multics command processor to loop n times, executing the 
specified Multics command <command>; n is an integer from 1 to 99999999 (e.g., 
.rpt 10 who). 

.pmc m n displays machine conditions in octal starting with machine condition set m 
for n sets. The integer m therefore represents a negative index from the last set 
of machine conditions stored (e.g., the request ".pmc 8 2" would be interpreted to 
mean, "display two sets of machine conditions starting from the last machine 
conditions stored at position 8"). If n is not specified, then all machine 
conditions starting at m to the last machine conditions stored are displayed. If 
neither m nor n are specified, all sets of machine conditions are displayed. 

.pmci m n same as .pmc above except that the machine conditions are displayed in 
interpreted format. 
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.pscu m n same as .pmc above except that only the System Control Unit (SCU) data 
for the specified number of machine conditions is printed, displayed in interpreted 
format. 

.hr m n displays history registers in octal, starting with history register set m for n 
sets. The variables m and n are defined as in .pmc above. 

.hrou m n same as .hr above except that only the Operations Unit (OU) history 
register is displayed in octal. 

.hrcu m n same as .hr above except that only the Control Unit (CU) history registers 
are displayed in octal. 

.hrdu m n same as .hr above except that only the Decimal Unit (DU) history registers 
are displayed in octal. 

.hrau m n same as .hr above except that only the Appending Unit (AU) history 
registers are displayed in octal. 

.hranl m n same as .hr above except that the specified number of history registers are 
displayed in interpreted format 

.hrlgd produces a list of abbreviations used with the .hranl request above. 

The mc_trace command invokes a condition handler for the "any_other" condition. 
When any unusual system condition is encountered, a message indicating the condition 
that was raised is displayed on the error_output I/O switch, and control is passed to 
the request loop. At this time, any of the valid requests described above can be 
entered. For further information on system conditions, refer to the Multics 
Programmer's Reference Manual, Order No. AG91). 

ACCESS REQUIRED 

To use mc_trace, you must have re access to phcs_. 
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EXAMPLES 

Assume that you have written a program that generates an op_not_complete fault while 
executing a csl (combine bit strings left) EIS instruction in a particular sequence (e.g., 
descriptors fall on page boundaries). This is clearly a hardware problem, but because 
it only occurs when a particular set of events take place, it is very difficult for the 
CSR to trouble-shooL For simplicity, call this program onc_csl. To run this program 
under control of mc_trace, execute the following sequence of commands: 

mc_trace onc_csl 

start trace with default buffer size of 5K words. 
— > . .set__proc_requi red a 

run with only one processor, in this case processor a. 
— > . .onc_csl 

execute the program onc_csl 
op_not_compl ete condition raised, enter command. 

At this point, the op_not_complete condition has occurred, and the machine condition 
history for the last 103 machine conditions should be preserved in the machine 
condition buffer. You can now selectively display these machine conditions. 

— > ..set_proc_required 

reset set_proc_required (run on any processor now) 

— > ..file_output onc_trace 

direct the output from the user_output I/O switch to the file named onc_trace 
created in your working directory. 

— > .pmc 

display the entire machine condition buffer. In this case, the output goes to the 
onc_trace file. 

— > .pmci 

additionally display the machine conditions in interpretive format. 
— > .pscu 

also display only SCU data in interpretive format. 
— > .hr 1 

display history registers from last fault (in this case, the op_not_complete fault) 
in octal format 

— > .hranl 1 

display a c-omposite analysis of the last set of history r^sters= 
— > .hranl 2 1 

display a composite analysis of the next to last set of history registers. 
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— > ..revert_outpui 

direct the output from the user_output I/O switch from the onc_trace file back 
to your terminal. 

— > ..dprint onc_trace 

print the onc_trace file on a remote printer. 

— > .q 

return to Multics command level. 

If the op_not_complete fault does not occur on a consistent basis and you suspect that 
it only occurs randomly when a particular sequence of page faults and interrupts 
occurs, you can use another program called "flush", which generates heavy paging 
activity, and can loop on these commands several times by executing the following line 
in place of the onc_csl command line: 

— > .rpt 99999999 f lush;onc_csl 

op_not_compl ete condition raised, enter command 

— > 

At this point, you can proceed as in the above example and print the machine 
conditions to a file or display them on the terminal. 

OUTPUT PRODUCED WITH THE .PMC, .PMC I, AND .PSCU REQUESTS 
.pmc REQUEST 

The .pmc request produces an octal dump of the machine conditions, separated by the 
logical data in the machine conditions (e.g., pointer registers, processor registers). The 
format is dependent on the state of the user_output I/O switch. If the user_output 
I/O switch is attached to a file or a terminal with a line length greater than or equal 
to 104 characters, then the output is formatted in lines of eight octal words per line. 
If the user_output I/O switch is attached to a terminal with a line length less than 
104 characters per line, then the output is formatted in lines of four octal words per 
line. 
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**>'«j'c*Mach i ne Conditions at mc__trace_buf f er 1 
Pointer Registers 

000035000043 00it646000000 0000170000^*3 000000000000 
000062000043 005362000000 000135000043 000000000000 
000014000043 006712000000 000062000043 000000000000 
000062000043 004060000000 000356400043 000000000000 

Processor Registers 

011127005716 000000000031 060614000030 000015000720 
000000000012 000000000004 000000000000 001714442000 

SCU Data 

000113050202 000000000043 400356000004 000000540000 
044571000200 000000000400 700000100440 000140100540 

Software Data 

121040000012 420040000006 000000000000 000000000000 
000000000000 000000000000 000000104422 532243555724 

EIS Pointers and Lengths 

000400000000 000400000000 000000000070 004077777774 
000102000030 000000000000 030356000004 000000000077 

.pmci REQUEST 
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The .pmci request displays the machine conditions in an interpreted format, as shown 
below. 

j'ii!tj'!fjVj'cMach i ne Conditions at mc_trace_buf f er 1 24lO»''t^i*** 



pro (ap) 35 
prl (ab) 17 
pr2 (bp) 62 



if646 bound_sss_wi red_| 4646 
0 sst_seg|0 
5362 pds|5362 



pr3 (bb) 135lO di r lockt^seg |0 



pr4 dp) 14 
pr5 (lb) 62 
pr6 (sp) 62 



6712 as_l inkage|6712 



0 pds 
4060 pds 



0 

4060 



pr7 (sb) 35b 1 0 comp1ex_decimal__op_|0 (bound_pll_runt ime_|0) 



xO 11127 xl 5716 x2 0 x3 

x4 60614 x5 30 x6 15 x7 
a 000000000012 q 000000000004 e 0 
Timer reg - 1714442, Ring alarm reg - 0 



31 
720 



SCU Data: 
240 



000113050202 000000000043 400356000004 000000540000 
044571000200 000000000400 700000100440 000140100540 



(DF1) Page Fault (43) 

By: 113|44571 bound_f i 1 e_sys tern | 4457 1 

Referencing: 356 jO complex_dec imal_op_j0 (bound_pl l_runt ime__IO) 

On: cpu a (#0) 

Indicators: ^bar 

APU Status: sd-on, pt-on, ptw 

CU Status: rfi 

Instructions: 

246 700 000 100 440 mlr (r 1 ) , () , f i 11 (700) 

247 000 140 100 540 mlr (pr , r 1 ) , (pr , r 1) , f i 11 (000) 

Time stored: 05/31/77 1355-3 mst Tue (104422532243555724) 
Ring: 0 

EIS Pointers and Lengths: 

260 000400000000 000400000000 000000000070 004077777774 

000102000030 000000000000 030356000004 000000000077 



.pscu REQUEST 
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The .p«cu request displays only the SCU data from the machine conditions in an 
interpreted fashion, as shown below. 

jV?'c»'c*>VMachine Conditions at mc_trace__buf 1 2^tlO'f'C*** 

SCU data at mc__trace_buf 1 2^*0 

2^0 000113050202 OOOOOOOOOOi+3 400356000001+ 0000005^0000 
0^+1*571000200 000000000400 700000100440 000140100540 

(DFl) Page Fault (43) 

By: 113|44571 bound_f 11 e_sys tern 1 44571 

Referencing: 356|0 compl ex_dec imal_op_| 0 (bound_pl l_runt ime_|0) 

On: cpu a (#0) 

Indicators: "^bar 

APU Status: sd-on, pt-on, ptw 

CU Status: rfi 

I nstruct i ons : 

246 700000 100 440 mlr (r 1 ) , () , f i 11 (700) 

247 000 140 100540 mlr (pr , r 1) , (pr , r 1) , f i 11 (000) 



OUTPUT PRODUCED BY THE .HR REQUEST 

The .hr request produces an octal dump of the history registers. The output is 
separated by the history register type being dumped. The format is dependent on the 
state of the user_output I/O switch. If the user_output I/O switch is attached to a 
file or a terminal with a line length greater than or equal to 104 characters, then the 
output is formatted in lines of eight octal words per line. If the user_output I/O 
switch is attached to a terminal with a line length less than 104 characters per line, 
then the output is formatted in lines of four octal words per line. If the .hrou, 
.hrcu, .hrdu, or .hrau requests are selected, only the requested history register type is 
dumped. 
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j'cj'cj'cj'ii'cHi story Registers at mc_trace_buf 1 2 10***** 



it (OU) Hist( 
137777012705 
177777012710 
114777012717 

135777012727 
123777000052 



ry Registers 
ii50000450300 
221000221 100 
220000220100 
7^1000741300 
446000446300 
440000440300 
621000621500 
431210431000 



Operations Un 

315000315100 

255000255300 

220006221340 

740000740300 

450000450300 

720000720500 

450000450300 

431210431 100 

Control Unit 
700137352120 
2001 17352000 
700137352120 
200117352000 
600137621 100 
200017431007 
300137370120 
300017352120 

Decimal Unit 
737757037737 
777757037737 
737757037737 
737757037737 
777757037737 
737757037737 
737757037737 
737757037737 



(CU) History 
000046050200 
027220050024 
000050050200 
027224050024 
000052050200 
020000042014 
027524050021 
034314042020 

(DU) History 
744243410017 
744243410017 
744243410017 
744243410017 
744243410017 
744243410017 
744243410017 
744243410017 



Reg i sters 

3001 17352120 

200017252100 

300137352120 

200017252100 

2001 1762 1100 

700137370120 

200117370000 

300005352046 

Reg i sters 

737757037737 

737757037717 

777757037737 

737757037717 

737757037737 

777757037717 

777757037737 

777757037717 



177777012707 
136777012711 
135777012720 
176777012722 
177757012726 
175777012730 
122777000051 
037777000054 



027342050020 
027574242100 
027344050021 
027576242100 
027566050014 
000054042200 
034304050024 
034314402002 



744243410017 
744243410017 
744243410017 

7442434 100 17 

744243410017 
744243410017 
744243410017 
744243410017 



024520464775 

000272204775 

024520504775 
000272244775 
024520524775 

000200004775 
027555244775 
026403144000 



Appending Unit (AU) History Registers 
002342006066 027555724775 003576007262 

002342006066 027553424775 002346001420 
002342006066 027555744775 003576007262 
002342006066 027553444775 002346001420 
0023420.06066 027555764775 003576007262 
003576001420 000275664775 003576001420 
003576007262 024520544775 002342006066 
002556001420 000343044775 002552007370 
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OUTPUT PRODUCED BY THE .HRANL REQUEST 

The .hranl request produces a composite analysis of the history registers in the trace 
buffer. The output produced is dependent on the state of the user_output I/O switch. 
If the user_output I/O switch is attached to a terminal with a line length less than 
104 characters, the output appears as below. If the user_output I/O switch is attached 
to a file or a terminal with a line length greater than or equal to 104 characters, then 
the octal representation of the history registers is displayed in addition to the sample 
below: 

}V**sV*Hi story Registers at mc_trace_buf 1 210***** 
Composite Analysis of History Registers 
HR c 



id## 

1 77 


1 r onfri 


tao 

LGI^ 


y 




nf f ^f»t 


fnr' 


flags 












CU 1 




n* 


] 


h 1 

H I p 






pi 


pa 


r \ 
1 1 


1 c 


w i 


i t 

1 u 




AU 2 








7 6 


336046 


ij 


ap 


sm 


pm 












II 


11" 


II 


^ J** 




Ix 
H 


pa 


r 1 




1 L 


r 1 
\, 1 






AU 3 








1 £. ^ 




1| 


ap 


sm 


|i/iii 










CU 3 


II 




d 


J-t 


27220 


k 


pa 


1 c 


cl 


dr 








AU k 










27220 


k 
















CU it 


46 spr 1 2 




0 


234 


2757^1 


Ik 


pa 


i t 


cs 










AU 5 








12 5 


533574 


k 


ap 


sm 


pm 










CU 5 


hT epp2 


n* 




415 


50 


k 


pi 


pa 


r 1 


i c 


wi 


i t 




AU 6 








7 6 


336050 


4 


ap 


sm 


pm 










CU 6 


II 


n* 


n 


234 


27344 




pa 


r i 


i c 


wi 


i t 


cl 


pb 


AU 7 








12 5 


533344 


k 


ap 


sm 


pm 










CU 7 


II 




d 


234 


link 


k 


pa 


i c 


cl 


dr 








AU10 










link 


k 
















CUlO 


50 spri2 




0 


234 


1151^ 


Ik 


pa 


i t 


cs 










Aun 








12 5 


51151^ 


4 


ap 


sm 


pm 










CUl 1 


51 eaxl 




i 


415 


52 


4 


pi 


pa 


i c 


wi 


i t 






AU12 








7 6 


336052 


4 


ap 


sm 


pm 










CU12 






d 


415 


27566 


4 


pa 


i c 


i t 


ol 


dr 






AU13 










27566 


k 
















0Ul6 














rb 


rs 


of 


-d 


ar 


qr 


xl 


CU13 


52 fid 


d1 


d 


415 


20000 


4 


pa 


0I 


dr 










AUlit 










20000 


k 
















0U17 














d1 


rs 


of 


-d 


ar 


qr 




CUlU 


53 epp4 


n* 


i 


415 


54 


4 


pi 


pa 


r i 


i c 


wi 


i t 




AU15 








7 6 


336054 


4 


ap 


sm 


pm 










CU15 


II 


n* 


n 


234 


27524 


4 


pa 


r i 


i c 


wi 


i t 


cl 


pb 


AU16 








12 5 


533524 


k 


ap 


sm 


pm 










CUl6 


II 




d 


255 


43742 


k 


pa 


i c 


cl 


dr 








AU17 










43742 


4 
















CUI7 


54 epp2 


n* 


n 


255 


43752 


4 


pa 


r i 


i t 


cl 








AU20 








4 4 


3225752 


k 


ap 


sm 


pm 
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OUTPUT PRODUCED BY THE .HRLGD REQUEST 

The .hrlgd request produces a list of the abbreviations used with the .hranl request 
above. 



Abbreviations used in History Register Analysis 
CU Legend 



cy = cycle type (d = direct operand) 
(i = i nstr . f etch,o=operand, F=f aul t) 
(n=i ndi rect,x=xec,5'«=nop,e=E i S) 
mc = memory command 
(00=rrs,sp; Oit=rrs,dp; 10=rcl,sp) 
(12=rmsk,sp; l6=rmsk,dp; 20=cwr,sp) 
(24=cwr,dp; 32=smsk,sp; 36=smsk,dp) 
(40=rd/lck; 5^=rgr; 56=sgr) 
(60=wrt/ul ck ; 62=con; 66=xec; 72=sxc) 
»>f lags«< 



»f lags«< 



,0U Legend_ 



-y 

br 

cl 
cs 
dr 
fa 
i c 
it 
i n 
ol 

OS 

pa 
pb 
pi 
pl 
pn 

•I-!- 

F - 

ra 
r i 

rp 
sa 
s i 
tr 
wi 
xa 
xe 
X i 
xo 



i nval i d 



memory address 
BAR mode 

control unit load 
control unit store 
direct operand 
prepare fault address 
I C va 1 ue is odd 
AR/PR reference 
inhibited instruction 
operations unit load 
operations unit store 
prepare operand address 
port busy or data from cache 
prepare instruction address 
port select logic not busy 
prepare final indirect address 
prepare operand tally 
request alter word 
request indirect word 
executing repeat 
store alter word 
store indirect word 
transfer condition met 
request instruction fetch 
prepare execute interrupt address 
execute double from even i CT 
execute interrupt present 
execute double from odd I CT 



9b 
ar 
dl 
d2 
dl 
du 
i n 
it 
oa 
oe 
of 
om 
on 

OS 

qr 

rb 

rp 
rs 
sd 
-d 
xO 
xl 
x2 

x3 
xit 

x5 
x6 

x7 



9-bit byte (IT modifier only) 

A-register in use 

f i rst d i V i de eye 1 e 

second divide cycle 

direct lower operand 

direct upper operand 

first ou cycle 

IT character modifier 

mantissa alignment cycle 

exponent compare cycle 

final OU cycle 

general OU cycle 

normalize cycle 

second cycle of multiple ops 

Q-register in use 

opcode buffer loaded 

primary register loaded 

secondary register loaded 

store data available 

data not available 

index 0 in use 

index 1 in use 

index 2 in use 

index 3 in use 

index U in use 

i ndex 5 i ri use 

index 6 in use 

index 7 in use 
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DU Legend APU Legend 

mc = data mode (b,^,6,9.w) seg# = SDWAMR and PTWAMR numbers if 

offset = descriptor counter corresponding MATCH bits are set, 

»>flags«< offset = final store address 



()a 


1 = 


= prepare alignment count for 


mc 




ring number (TSR.TRR) 






numeric operand (If 2) 








aO 




= load alpha operand (1,2) 


»>f lags«< 


a] 


— 


adjust length 


an 




f I ns 1 aririrp<i«^ nnn — nao^ri 


as 


— 


alpha store 


ap 




final addre^^ naasd 


bd 


— 


binary-decimal execution 


f 




access violation or directed 












f aul t 


bg 


— 


blanking gate 


fd 




fftch dp^cr iotor seament' PTW 


cO 


— 


force stcO 


fh 




f au 1 1 wa i t i ng 


eg 




character operation 


fs 




fetch SDW 


dO 




= descriptor active (1,2,3) 


md 




mori i f" V Hp^pr i ntr^r ^Annipnl' PTW 


da 




data ava i 1 ab 1 e 


mp 




mod i f V PTW 


db 


— 


decimal-binary execution 


pl 




fetch PTW 


dd 


— 


decimal unit idle 


P2 




fetch PTW+1 


di 


— 


decimal unit interrupted 


pm 




MATCH i n PTWAM 


dl 


— 


decimal unit load 


sm 




MATCH in SDWAM 


ds 




decimal unit store 








e i 


— 


mi d- i nstruct i on interrupt enabled 




en 


— 


end instruction 








es 


— 


end sequence 








ff 


— 


floating result 








f 1 


— 


first data buffer load 








fp 


= 


first pointer preparation 








fs 


= 


end sequence 








1 0 




= load descriptor (1,2,3) 








Id 


— 


length = direct 








If 


= 


end first pointer preparation 








Iv 




level < word size 








Ix 


= 


length exhaust 








1< 


— 


length < 128 








mp 


= 


executing MOPs 








nO 




= load numeric operand (1,2) 








nd 




need descriptor 








ns 




numeric store 








op 




operand ava i 1 abl e 








pc 




alpha packing cycle 








pl 




prepare operand length 








PP 




prepare operand pointer 








rO 




= load rewrite register (1,2) 








re 




write-back partial word 








rf 




round i ng 






— DU Legend 


rl 




rewrite register 1 loaded 


xg 




exponent network 


rw 




du=rd+wt control interlock 


xm 




extended al ,ql modifier 


sa 




select address register 


+g 




add-substract execution 


sg 




shift procedure 


*g 




mul ti ply-divide execution 
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Name: mcs version 

SYNTAX AS A COMMAND 
mcs_version {fnp_tag} 
FUNCTION 

prints the version of the core image most recently loaded into the specified FNP. 

ARGUMENTS 

fnp_tag 

where fnp_tag is the identifier of the FNP whose version is to be printed. It can 
be a, b, c, d, e, f, g, or h. If it is omitted, a is assumed. 



Name: meter fnp idle 

SYNTAX AS A COMMAND 

meter_f np_i d 1 e fnp_name {-control -args} 

FUNCT/ON 

reads FNP idle metering information at specified intervals and stores the information 
in a segment for later viewing through the display _fnp_idle comm.and. 

ARGUMENTS 

fnp_name 

identifies the FNP for which idle time is to be recorded. 

CONTROL ARGUMENTS 

-directory path, -dr path 

specifies that the segments in which idle time information is to be stored are to 
be created in the directory with pathname path. The default is the user's working 
directory. Segment names are of the form fnp_idle_data.F.MMDDYY.HHMMSS.I 
where F is fnp_name, MMDDYY.HHMMSS is the starting date and time of 
recording, and I is the specified interval in minutes. 

-interval N 

specifies that metering information is to be sampled every N minutes. The default 
is 1. 
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-stop, -sp 

terminates meter reading on this FNP. No other control argument may be 
specified with -stop. 

ACCESS REQUIRED 

Use of this command requires access either to the metering gate gate or the phcs_ 
gate. 

NOTES 

Information is appended to the idle time segment until the -stop control argument is 
encountered or the process terminates. Maximum length of an idle time segment is 
64K (to avoid exhausting a 256K ASTE). If a segment becomes full, a new one is 
created. On average, talcing readings at one-minute intervals would fill a 64K segment 
in a little over three weeks (if a single process in which the command was invoked 
were to run that long). 

Each invocation of the command creates a new segment. 

EXAMPLES 

The command 

meter_f np_i d 1 e a -interval 5 

creates a segment in the working directory into which will be stored idle time meter 
readings taken on FNP "a" at five-minute intervals. 



Name: meter gate, mg 

SYNTAX AS A COMMAND 

mg STR {entry_nm} {-control__arg} 

FUNCTION 

is used to interpret and print per-system metering information for entries in specified 
hardcore gates. 
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meter _gate 



ARGUMENTS 
STR 

is the name of the gate segment to be examined; i.e., hcs_, phcs_, hphcs_, ioi_, 
hc_backup_, etc. 

entry_nm 

is the name of a single entry in the specified gate. Only the information for that 
entry is printed. If entry_nm is not specific, information for all entries is 
printed. No control argument can be given if an entry_nm is specified. 

CONTROL ARGUMENTS 

-average, -av 

sorts the output on the average time spent in each entry. 

-call, -cl 

sorts the output on total calls to each entry, 
-page, -pg 

sorts the output on the average number of page faults in each entry, 
-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 
the last call with -reset specified. If -reset has never been given in a process, it 
is equivalent to having been specified at system initialization time. 

-time, -tm 

sorts the output on the total time spent in each entry. 
NOTES 

If the meter _gate command is given with no control argument, it does not sort the 
output. 

The output header consists of the time the system was brought up, the current time, 
and the total charge time (which equals total_cpu_time minus idle_time). Also printed 
is the total number of calls to the gate, the amount of time spent in the entries that 
were called, and the percentage of total charged time that was spent in the entries 
that were called. 
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meteT_gate 



Metering information is collected only for gate segments defined with the "hgate" 
macro, and only for those entries in the segment defined with the "gate" macro (refer 
to the gate_macros.incl.alm include file for these macros, and refer to the source 
listing of a particular gate to apply this principle). For example, some hardcore gate 
entries are defined with the "fgate" macro for efficiency or because ring 0 stack 
history is abandoned during the call (e.g., hcs_$block); such gate entries are not 
metered. 

The following is a "brief description of the variables printed out by the meter_gate 
command. 

calls 

is the total number of times the gate entry point was called. 

pent 

is the percentage of total charge time spent in the called segment 

avg 

is the average virtual lime in milliseconds spent in the called segment. 

pfault 

is the average number of page faults incurred during a call to a segment through 
the specified entry. 

entry name 

is the name of an entry point to the gate. 

EXAMPLES 

The following is an example of the information printed when the meter_gate command 
is invoked with hcs_ as the name of the gate segment to be examined- (See Appendix 
A for a representation of the configuration deck used to create the system from 
which the metering sample was taken.) 

Metering since 12/12/83 12^*7.2 mst Men. 
Total non-Idle time at 12/12/83 1302.6 mst 
Men = 1 hr, 12 min. 4 sec. 

Gate meters for hcs_: total calls = 136778. 

0 hr. 12 min. kk sec. or 17.675^ spent in calls through gate. 



lis 


pent 


avg 


pwa i t 


entry name 


17 


0.01 


15.00 


0.06 


add_acl_entr ies 


1 


0.00 


10.03 


0.00 


add_d i r_i nac l__entr 1 es 


1 


0.00 


17.32 


0.00 


add_ i nac 1 _entr i es 


79 


0.06 


30.75 


0.29 


append_branch 


6 


0.00 


9.70 


0.17 


append__l i nk 


kl 


0.00 


0.32 


0.00 


ass i gn_channel 


6 


0.00 


0.55 


0.00 


ass i gn__l i nkage 
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76 


0.01 


7.63 


0.00 


164 


0.04 


1 1 .23 


0.00 


k 


0.00 


5.96 


2.00 


90 


0.06 


31 .01 


0.34 


103 


0.09 


38.56 


0.21 


18 


0.01 


33.10 


0.06 


8 


0.00 


13.39 


0.13 


37 


0.00 


0.25 


0.00 


2369 


0.32 


5.85 


0.00 


1 182 


0.19 


7.01 


0.00 


28 


0.00 


6.56 


0.11 




0.00 


0.42 


0.00 


1610 


0.13 


3.55 


0.00 


983 


0.05 


2.34 


0.04 


2181 


0.20 


3.98 


0.05 


525 


0.01 


0.51 


0.04 


1718 


0.03 


0.81 


0.14 


74 


0.01 


6.13 


0.42 


2118 


0.84 


17.09 


1 .09 


262 


0.05 


8.65 


0.02 


1 


0.00 


1 .26 


0.00 


3714 


0.01 


0.1 1 


0.00 


47 


0.01 


5.74 


0.02 


3 


0.00 


7.12 


0.00 


127 


0.00 


0.10 


0.00 


903 


0.21 


9.87 


0.70 


43 


0.00 


0.26 


0.00 


230 


0.06 


1 1 .98 


0.01 


141 


0.03 


9.70 


0.01 


366 


0.00 


0.28 


0.00 


117 


0.03 


11.77 


0.42 


74 


0.01 


6.77 


0.00 


10 


0.00 


5.53 


0.00 


54 


0.01 


6. n 


0.09 


52 


0,00 


1.27 


0.00 


334 


0.08 


10.33 


0.49 


6546 


0.04 


0.25 


0.01 


60 


0.02 


15.87 


1.35 


370 


0.08 


9.78 


0.36 


753 


0.00 


0.12 


0.01 


1 


0.00 


0.16 


1 .00 


4575 


0.87 


8.24 


0.12 


1400 


0.25 


7.60 


0.52 


55 


0.03 


25.83 


0.51 


230 


0.06 


10.75 


0.01 


12 


0.06 


204.02 


1.25 


1 1 


0.00 


11.11 


0.00 


4 


0.00 


5.30 


0.00 


13 


0.00 


14.78 


0.69 


1649 


0.88 


23.15 


0.33 



chname_f i 1 e 

chname_seg 

comb i ne_l i nkage 

create_branch_ 

del entry_f i 1 e 

del entry_seg 

del ete_ac l_entr i es 

delete_channel 

f 1 ush_consecut i ve__pages 

f 1 ush_pages 

f orce_wr i te 

f s_g e t_a c c e s s_mod es 

f s_get_brackets 

f s_get_mode 

f s_ge t_pa t h_name 

f s_get_seg_ptr 

f s_search_get_wdi r 

f s_search_set_wd i r 

get_access_c 1 ass 

get_access_c 1 ass_seg 

get_al arm_t imer 

get_author i zat i on 

get_def name_ 

get_d i r_r i ng_brackets 

get_i ni t i al_r i ng 

get_l i nk_target 

get_l p 

get_max_1 ength 

get_max_l ength_seg 

get_process_usage 

get_r i ng_brackets 

get_safety_sw 

g e t__s a f e t y__s w_s e g 

get_search_rules 

get_system_search__riiles 

get__uid_f i le 

get_uid_seg 

get_user_access_modes 

get_user_ef fmode 

h i gh_l ow_seg_count 

h i story_regs__set 

i ni t iate 

i ni t i ate_count 

i n i t i ate_search_ru 1 es 

1 ist_acl 

1 ist_di r 

1 i st_d i r_ac 1 

1 i st_di r_i nacl 

1 i st_i nac 1 

fnake_entry 
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meter_gate 



6914 


1 .59 




0. 35 


73 


0.00 


62 


0.03 


80 "^0 


0.13 


217 


0. 10 


g 


0.00 


3 


0.00 


12 


0 .00 






6953 
^ J J J 


0.21 




0.01 




0.98 


2 


0.00 


37 


0 .00 


1328 


0. 39 


7*5 


0 .02 


■ -> / 


0 0^ 


52 


0.13 


186 


0.42 


8r6 

c ^ w 




1 3 


0.00 


3030 


0.86 


2980 


0.53 


1031 


0.12 


25 


0.00 


1 3 


0 .00 


52 


0 .00 


5062 


0.23 


45 


0.00 


26 
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Name: meter rep 

SYNTAX AS A COMMAND 
meter_rcp {-control_args} 
FUNCTION 

prints information about devices controlled by the resource control package (RCP). 
CONTROL ARGUMENTS 
-all, -a 

displays meters for both locks and devices. 

-device STR, -dv STR 

displays meters only for the device named STR. This control argument cannot be 
used with the -lock or -type control arguments. 

-lock 

displays only meters for locks. The default is to display meter information only 
for devices and not for locks. 

-long, -Ig 

displays additional information about devices/ locks (as selected by the other 
control arguments) that is not otherwise printed (e.g., for -type, an assignment 
histogram; for -lock, four lines of totals). 

-report_reset, -rr 

generates a full report and then performs the reset operation. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 

the last call with -reset specified. If -reset has never been given in a process, it 

is equivalent to having been specified at system initialization time. 

-type STR, -tp STR 

displays meters only for devices of the type specified by STR. This control 
argument cannot be used with the -lock or -device control arguments. STR can 
be tape, disk, console, printer, punch, reader, or special. 

NOTES 

If the meter_rcp command is given with no control arguments, it prints information 
for all devices only (no locks). 
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The following is a brief description of the variables printed if the -lock control 
argument is specified. 

% time locked 

is the percentage of time spent locked. 

% time waiting 

is the percentage of time waiting for locks. 

% number of waits 

is the percentage of the number of attempts to lock that required a wait. 



If the -type control argument is specified, the following variables are printed for that 
type only. This same information is printed for all device types if no control 
argument is given, and for the named device if the -device control argument is given. 

Total assignments 

is the number of times the device has been assigned during the metering interval. 
Total errors 

is the number of I/O transfer errors for the device during the metering interval. 
Total time assigned 

is the time (in hours, minutes, and seconds) the device has been assigned during 
the metering interval. 

% time assigned 

is the percentage of the metering interval that the device has been assigned. 
EXAMPLES 

The following is an example of the information printed if the meter_rcp command is 
specified with the -lock control argument 



Total time metered = 1 hours, 29 minutes, 3^ seconds 

Lock meters for rcp_com_seg: 
% time locked = 0 % 

% t i me wa i t i ng = 0 % 

% number of waits = 0 % 

Lock meters for rcp_data: 
% time locked = 0 % 

%■ t i me wa i t i ng = 0 % 

% number of waits = 2 % 
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The following shows a sample result of invoking the meter_rcp command with the 
-type control argument specifying tape. 

Total time metered = 0 hours, 15 minutes, 29 seconds 

Meters for device type tape_drive: 
Meters for tapa_06 

Total assignments = 

Total errors = 

Total time assigned = 

% time assigned = 
Meters for tapa_09 

Total assignments = 

Total errors = 

Total time assigned = 

% time assigned = 

Finally, if the command: 

meter_rcp -device dska_05 

is given, the following information is printed. Giving the command with no control 
arguments produces a report that would include both this and the above example's 
information, as well as the same type of information for all other RCP devices. 

Total time metered = 0 hours, 5 minutes, 37 seconds 
Meters for dska_05 

Total assignments =1 

Total errors = 0 

Total time assigned = 0 hours, 5 minutes, 37 seconds 

% time assigned = 99 % 



1 

0 

0 hours, 13 minutes, 53 seconds 
89 % 

1 

9 

0 hours, 1 minutes, 32 seconds 
9 % 



Name: meter signal 

SYNTAX AS A COMMAND 
meter_signal {-control_args} 
FUNCTION 

measures the performance of the Multics signalling mechanism. It sets up an 
environment of condition handlers and stack frames, and then causes a specified 
number of zerodivide faults to occur. The calendar clock is read before each fault 
and again as the first operation in the zerodivide condition handler. The difference 
between these values is recorded and printed on the terminal. The mean and minimum 
values for all zerodivide faults caused in an invocation are computed. 
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CONTROL ARGUMENTS 

Each control argument must include a decimal value (N) and can be specified in 
any order. 

-nfaults N 

specifies how many zerodivide faults to cause. One zerodivide fault is the default 
-n frames N 

specifies the number of stack frames to be established between the frame 
containing the zerodivide handler and the frame that causes the fault. The fault 
occurs in the same frame that established the handler if the value is one; this is 
the default. 

-nhandlers N 

specifies the number of handlers for dummy conditions to be established in each 
stack frame. Handlers are established for the conditions meter_signall through 
meter_signalN where N is the value specified. The default is that no dummy 
interrupt handler is established. 

-unclaimed N 

specifies that an unclaimed_signal handler should be established instead of the 
zerodivide handler. The unclaimed_signal handler is established in the Nth frame 
where N is the value specified. Stack frames are numbered from 1 to p, where p 
is the number in the -nframe control argument. The default is that no 
unclaimed_signal handler is established. 

EXAMPLES 

The command line: 

meter_s i gnal -nfaults 25 -nframes 5 -nhandlers 2 -unclaimed 3 

causes 25 faults. Five stack frames are laid down before any faults are caused. Each 
frame contains handlers for meter_signal_l and meter_signal_2. An unclaimed_signal 
handler appears in the third frame. 
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Name: monitor cache 

SYNTAX AS A COMMAND 

moni tor_cache {cpu_tag} {-control_args} 

FUNCTION 

initiates and controls automatic monitoring of cache memory error data saved during 
normal fault processing. This command constantly monitors the cache memory error 
data to provide a warning when error rates become excessive. To compare error rate 
threshold values, use a per process threshold or the -priv control argument described 
below. For information pertaining to changing the per -system defaults and setting up 
per-process values that are different from the per-system defaults, see "Changing the 
Threshold Values" below. To display the current threshold values, use the 
display_cache_threshold command. 

ARGUMENTS 

cpu_tag 

identifies the tag(s) of the CPU(s) whose cache error rates should be monitored. 
If no CPUs are identified, all possible CPUs will be monitored. 

CONTROL ARGUMENTS 

-brief, -bf 

suppresses the "CPU below cache error threshold" message when the error rate is 
within the specified threshold limits. This does not suppress the warning when the 
error rate is above the threshold values. This is the default 

-long, -Ig 

emits a "CPU below cache error threshold" message on the user_output I/O 
switch. 

-cpu cpu_list 

an alternate method of specifying the list of the tags of the CPUs whose cache 
error rates should be monitored. 

-priv 

causes warning messages of "Cache above error threshold for CPU" to be written 
into the syserr log and the bootload console with an audible alarm. This control j 
argument sends the polling message described under -long above to the syserr_log i 
instead of the user_output I/O switch. You must have re access to the hphcs_ i 
gate to use this control argument i 

-stop, -sp I 

stops monitoring for the CPUs specified in the cpu_tag argument or the -cpu i 

control argument If no CPU tags have been specified, then monitoring for all i 

CPUs is terminated. i 
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-start, ST 

resumes monitoring for the CPUs specified in the cpu_tag argument or the -cpu 
control argument Monitoring will continue with the next scheduled cycle. 

-time N, -tm N 

specifies the monitoring interval in minutes, where N is a decimal integer. The 
default time is 15 minutes. 

ACCESS REQUIRED 

You must have re access to the phcs_ gate to use this command. 
CHANGING THE THRESHOLD VALUES 

The per-system and per-process default threshold values are defined in 
>system_library_tools>cache_threshold_defaults. This segment is created by a cds source 
segment of the same name. To change the system default values, you must change this 
source segment, recompile it, and install the generated object in >tools. A per-process 
threshold that is different from the per-system values may be created by performing 
the same operations, except that the per-process threshold should be found in the 
process' object search rules before > tools or the threshold may be specifically initiated. 

NOTES 

The monitor interval is closely associated with the threshold values in that the 
threshold is specified in terms of an acceptable error rate N in X time. The default 
threshold values are expressed as a per_hour_error rate. 



Name: monitor sys log, msl 

SYNTAX AS A COMMAND 

msl {log_se lector} {-contro1_args} 

FUNCTION 

monitors activity in system logs. Contents of the selected logs are periodically 
examined, and any new messages are printed on the terminal or passed as arguments 
to a specified command line. Control arguments determine what action the command 
performs, and also supply message selection and formatting options. 
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There are three types of control arguments: log selection, action, and monitoring 
control arguments. Only one action control argument may be specified in any given 
invocation of the command. For all actions (except -status), a log must be specified; 
for some actions (-update, -on, -off, -remove, -status), -all may be specified to 
select the log, indicating that the action applies to all logs currently being monitored. 
All other control arguments specify monitoring operations: message selection, message 
processing, message format. A separate set of monitoring options is kept for each log 
being monitored. A specific log may be monitored more than once, by specifying 
-add to establish separate monitors; this is useful when different sets of monitoring 
options are desired to process messages from the same log differently. 

ARGUMENTS 

log_selector 

is the pathname of a log to be monitored. The pathname must specify the first 
segment in a log. This argument is incompatible with any of the log selection 
control arguments. 

If a log is selected, either by pathname or one of the control arguments below, 
and no "action" is specified, monitoring is started or updated, as appropriate (see 
-update, below). To replace the monitor information for a log, or start an 
independent monitor with different parameters, -replace or -add must be 
specified. For all actions except -status, either a log pathname or a log selection 
control argument must be specified. 

CONTROL ARGUMENTS FOR LOG SELECTION 

-admin 

specifies that the admin log is to be examined. The admin log is called 
"admin_log", and is located in the >scl>as_logs directory. This argument is 
incompatible with any of the other log selection control arguments, or an explicit 
log pathname. 

-all, -a 

specifies that the monitor information for all lop is to be changed. This 
argument is incompatible with any of the other log selection control arguments, or 
an explicit log pathname. 

-answering_service, -as 

specifies that the answering service log is to be examined. The answering service 
log family is called "log", and is located in the >scl>as_logs directory. This 
argument is incompatible with any of the other log selection control arguments, or 
an explicit log pa^name. 
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-dm_system, -dms 

specifies that the data management system log for the process's current AIM 
authorization is to be examined. The data management log family is called 
"dm_system_log", and its location depends on the AIM access class of the log. 
This argument is incompatible with any of the other log selection control 
arguments, or an explicit log pathname. Reading the log requires access to the 
dm_admin_ gate. 

-mc_log log_name, -mcl iog_name 

specifies that the message coordinator (daemon) log named LOG_NAME is to be 
examined. All message coordinator logs are located in the >scl>as_logs directory; 
their names depend on the daemon to which they belong. This argument is 
incompatible with any of the other log selection control arguments, or an explicit 
log pathname. 

I -number N, -nb N 

I specifies that the monitor information for log number N is to be changed. The 

I log numbers are listed in the output from "monitor_sys_log -status". This 

I argument is incompatible with any of the other log selection control arguments, 

I -all. or an explicit log pathname. 

-syserr 

specifies that the syserr log is to be examined. The syserr log family is named 
"syserr„log". The first segment in the family is >sll>syserr„log; there may be a 
history segment in >sll, and older history segments are in the directory 
>scl>syserr_log. This argument is incompatible with any of the other log selection 
control arguments, or an explicit log pathname. 

I CONTROL ARGUMENTS FOR ACTION TO BE PERFORMED 

I -add 

I adds the specified log to the list being monitored, with the parameters specified 
I by the other control arguments. This is incompatible with -all and -number, and 
I any other "action" control argument 

-off 

turns monitoring off for the specified log(s), remembering the monitoring 
parameters. Monitoring must already have been started on the specified log. This 
is incompatible with the other "action" control arguments. No monitoring 
parameters may be specified with this control argument. 

-on 

turns monitoring back on for the specified log(s), reversing the effect of -off. 
Monitoring must already have been started on the specified log. This is 
incompatible with the other "action" control arguments. No monitoring parameters 
may be specified with this control argument. 
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-remove, -rm i 

removes the specified log(s) from the list being monitored. Monitoring must i 

already have been started on the specified log. This is incompatible with the i 

other "action" control arguments. No monitoring parameters may be specified with i 

this control argument. i 

-replace, -rp 

replaces all the monitoring parameters for the specified log(s) with those specified 
by the other control arguments. The log(s) must already be being monitoreid; it is 
an error to specify a log pathname or selection control argument identifying a log 
not being monitored already. This is incompatible with -all and any other 
"action" control argument 

-status, -St I 

displays the status of monitoring for the specified log(s), or for all logs currently i 

being monitored if none is specified explicitly. This is incompatible with the i 

other "action" control arguments. No monitoring parameters may be specified with j 

this control argument. i 

-update, -ud i 

if the specified log is not already being monitored, monitoring is started for the i 

specified log. Otherwise, the monitoring parameters for the specified log are i 

updated by the other control arguments specified, as if those control arguments i 

had been specified at the end of the command line that initially started the | 

monitoring. This is incompatible with the other "action" control arguments. This i 

is the default i 

CONTROL ARGUMENTS FOR MESSAGE PROCESSING i 

-call COMMAND, -cl COMMAND | 

specifies a command line to be executed each time a message is selected from the | 

specified log(s). If the command is the null string (""), command line processing j 

is turned off, and new entries are printed on the specified switch, instead. The i 

command line receives the following parameters: i 

1) log prefix string 

2) date-time of message 

3) sequence number of message 
k) severity of message 

5) text of message 

6) data class of message 

7) expanded text of message 

Parameters 6 and 7 are only supplied if the message has binary data, and -expand | 
was specified. | 

-time N, -tm N 

specifies the monitoring interval, in seconds; the specified log(s) will be sampled 
once every monitoring interval. If the specified interval is zero, periodic 
monitoring is turned off. The default is ten seconds. 
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CONTROL ARGUMENTS FOR MESSAGE SELECTION 

-all_data_classes, -adc 

specifies that all messages, regardless of data class, are to be processed. This 
control argument cancels the effect of any preceding -match_data_class or 
exclude_data_class control argument. This is the default. 

-all_severities, -asv 

specifies that messages of all severities are printed. This cancels the effect of any 
previous -severity control arguments. This is the default. 

-all_text, atxt 

specifies that all messages, regardless of text contents, are to be processed. This 
control argument cancels the effect of any preceding -match or -exclude control 
argument. This is the default. 

-exclude_data_class CLASS, -exdc CLASS 

specifies that no messages with the specified data class are to be processed. 

-exclude STR-1 ... STR-n, -ex STR-1 ... STR-n 

specifies that no message whose text contains one of the specified strings (STR-1 
to STR-n) is processed. A string is interpreted either as a text string, which must 
be an exact substring of the message text, or, if surrounded by slashes, as a 
regular to match against the message text See the "Notes on String Matching" 
section below for details. 

-match_data_class CLASS, -mdc CLASS 

specifies that only messages with the specified data class are processed. See "Notes 
on Data Classes," below. 

-match STR-1 ... STR-n 

specifies that only messages whose text contains one of the specified strings 
(STR-l to STR-n) are processed. The strings are processed as for -exclude. 

-severity SEV-1 ... SEV-n, -sv SEV-1 ... SEV-n 

specifies that only messages of the specified severity (severities) are processed. The 
severity values (SEV-1 to SEV-n) may either be decimal integers, or ranges 
consisting of a pair decimal integers separated by a colon ("20:29"). If multiple 
severities are specified, or the -severity control argument is specified more than 
once, all messages with any of those severities are printed. A severity value must 
be between -100 and 100. See the "Notes on Severity Values" below for details. 

CONTROL ARGUMENTS FOR MESSAGE EXPANSION 

-all_data, -ad 

specifies that all messages with binary data are to be processed. This control 
argument cancels the effect of any preceding -match_data or -exclude_data 
control argument. This is the default. 
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-exclude_data STR-1 ... STR-n, -exd STR-1 ... STR-n 

no messages whose interpreted expanded data contains one of the specified strings 
(STR-1 to STR-n) is processed. The strings are processed as for -exclude. Note: 
this control argument merely matches against the textual interpretation of the 
expanded data; if this interpretation is to be displayed as well, the -interpret 
control argument must also be specified. 

-expand {CLASS-1 ... CLASS-n} 

specifies that binary data is to be expanded and displayed along with the message 
text for the selected messages. If a data class value (CLASS-1 to CLASS-n is 
specified, only binary data of the specified classes will be expanded; otherwise, all 
selected messages with binary data will be expanded. The type of expansion 
depends on whether the -octal or -interpret control arguments are also specified. 
See the "Notes on Data Classes" section below for details. By default, no 
messages are expanded. 

-interpret, -int 

specifies that the binary data in expanded messages is to be displayed as 
interpreted text, by calling the appropriate expand_XXX_msg_ program for the 
data class of the message. If the -octal control argument is also specified, the 
binary data is displayed both in interpreted form and as octal data. (Default) 

-match_data STR-1 ... STR-n, -md STR-1 ... STR-n 

specifies that only m^sages whose interpreted expanded data contains one of the 
specified strings (STR-1 to STR-n) are processed. The strings are processed as for 
-exclude. Note: this control argument merely matches against the textual 
interpretation of the expanded data; if this interpretation is to be displayed as 
well, the -interpret control argument must also be specified. 

-no_expand, -nex 

specifies that no messages are to be displayed with binary data expanded. This 
cancels the effect of any previous -expand control arguments. By default, no 
message are expanded. 

-octal, -oc 

specifies that the binary data in expanded messages is to be displayed in octal, 
rather than, or in addition to, the interpreted representation. If both octal and 
interpreted representations are desired, both the -octal and -interpret control 
arguments must be supplied. 

CONTROL ARGUMENTS FOR MESSAGE FORMAT 

-continuation_indent N, -ci N 

specifies that all messages are to be formatted for printing with continuation lines 
prefixed by N spaces, or, if the keyword "standard" or "std" is used in place of 
a number, with the continuation lines indented sufficiently to line up under the 
first character of the text of the message. The value of N must be between zero 
and fifty. By default, continuation lines are indented three spaces. 
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-date_format FORMAT_STRING, -dfmt FORMAT_STRING 

specifies a dale/time format string (see time_formal.gi.info or the Multics 
Programmer's Reference Manual, Order No. AG91) to be used when formatting 
the date when successive messages are printed with different dates. The date 
string is printed on a line entirely by itself, preceded by a blank line. If the 
date format string is blank, no date separators will be printed; this should be 
used if a -time_format string is specified that includes the date as well. The 
default date string is "'^9999yc-'^my-^dm '^da '^za", which prints as (for example) 
"1984-10-31 Wed est". 

By specifying null strings for date, time, and number formats, the log can be 
printed and saved, so that it can be compared to another log script later, without 
spurious mis-compares because the times and sequence numbers do not match. 

-duplicates, -dup 

inhibits the printing of "=" messages for messages whose text is the same as the 
previous message printed. All messages are printed exactly as they appear in the 
log. 

-indent N, -ind N 

specifies that all messages are to be formatted for printing prefixed with N 
spaces. The value of N must be between zero and fifty. The indentation is 
printed before any data associated with the message, including the message prefix. 
By default, there is no indentation. 

-linejength N, -11 N 

specifies the line length used when formatting message text and data for printing. 
The value (N) must be between 25 and 500. By default, it is the line length 
associated with the user_outpul I/O switch, or, if none (as- for an absentee), it is 
132 (for line printer output). 

-no_duplicates, -ndup 

prints "==" for messages whose text is the same as the previous message printed. 
This is the default. 

-number_format IOA_STRING, -nfmt IOA_STRING 

specifies an ioa_ string to be used when printing the sequence number for the 
message. If the string is null, no sequence number is printed with the message. 
The default is "'^Td". (See the Multics Subroutines and 110 Modules manual. 
Order No. AG93 for a description of ioa_ control strings.) 



2-342 



GB64-00 



monitor_sys_log 



monitor_sys_log 



-prefix STRING, -pfx STRING 

specifies that all messages are to be formatted with the specified string as a 
prefix. This prefix appears after the indentation (if any was specified). The 
prefix must explicitly include trailing spaces, if any are desired to separate the 
prefix from the message text The default prefix for a log is the entryname of 
the log except for logs specified by the log selection control arguments. The 
default prefix for a log selected by the log selection control arguments are listed 
below: 

Control Argument prefix 
-syserr 

-answer i ng__serv i ce 
-admi n 
-dm_system 



"SYSERR: 
"AS: " 
"ADMIN: 
"DMS: " 



-time_format FORMAT_STRING, -tfmt FORMAT_STRING 

specifies a date/time format string (see time_format.gi.info or the Multics 
Programmer's Reference Manual, Order No. AG91) to be used when formatting 
the message time portion of the message. If the string is null, no time is printed 
with the messages. The default time format is "iso_time", which prints as (for 
example) "23:21:59". 

MISCELLANEOUS CONTROL ARGUMENTS 

-data_class, -de 

specifies that the data class of each message is to be printed. 

-header, -he 

specifies that a header is to be printed giving the times and sequence numbers of 
the first and last messages processed. This is the default 

-no_data_class, -ndc 

specifies that the data class of each message is not to be printed. This is the 
default 

-no_header, -nhe 

specifies that no header is to be printed. 

-no_process_id, npid 

specifies that the processed stored with each message is not to be printed. This 
is the default 

-output_switch NAME, -osw NAME 

specifies that the messages are to be written on the named I/O switch. The 
default is user_output 
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I -procedure NAME, -proc NAME 

I specifies that entrypoints in the procedure called NAME are to be used instead of 

I entrypoints in log_read_ to read the log. This is used to read logs protected by 

I inner-ring subsystems, where the inner-ring subsystem provides a replacement 

I log-reading procedure. See "Access Required", below. 

I -process_id, -pid 

I specifies that the pr6cess_id stored with each message is to be printed. 

I NOTES ON STRING MATCHING 

The strings specified by -match and -exclude, or by -match_data and -exclude_data, 
are processed in sequence. An arbitrary number of strings may follow any of those 
control arguments, and each string will be treated as if it was preceded by another 
instance of the control argument, except that any string beginning with a hyphen and 
not immediately following one of the match/exclude control arguments is treated as a 
new control argument, and no more strings are picked up until the next match/exclude 
argument 

I A string may be either a text string, in which case it is tested simply to see whether 
I it is a substring in the message, or it may be a regular expression, which is matched 
I against the message. A string will be interpreted as a regular expression if it begins 
I and ends with "/" characters. 

I Each log message is processed against the set of strings, matching its text (or data) to 
I see if it contains the string. There are two simple cases: only match strings, and only 
I exclude strings. In the case of only match strings, any log message that matches any 
j of the strings will be printed. In the case of only exclude strings, a log message will 
I be printed only if it matches none of the strings. 

1 The more complicated case where match and exclude strings are mixed is handled as 
I follows: test the message against each string in turn. If the message matches, and the 
] string is a "-match" string, the "print-this-message" flag is set on. If the m^age 
I matches, and the string is a "-exclude" string, the flag is set off. Otherwise, the flag 
I is unaffected. The flag's initial value is on if the first string was a "-exclude" string, 
] and off if the first string was a "-match" string. 

I NOTES ON DATA CLASSES 

A data class is a short string (1 to 16 characters) stored with any message that 
contains binary data, and is used to identify the expander procedure used to expand 
the data into its interpreted textual form. The data class is specified when the 
message is placed into the log. 

I The data class "syserr" identifies an old-style syserr log message. The "syserr binary" 
I code (see syserr_binary_defs.incl.pll for a list) is the first word of the data in the 
I message; the remaining words of data are the real binary syserr data. 
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ACCESS REQUIRED 

For all except inner-*ring logs, read permission is required on the log segments 
themselves, and status permission is required on their containing directories. If an 
access error is encountered searching for older history logs, the search is stopped at 
that pomt, and no further history will be available. For the logs selected by control 
arguments, the control argument descriptions list the standard history directories for 
the logs. 

For inner-ring logs (the data management system log is the only standard inner-ring 
log), access to the logs is required, as is access to the gate used by the log-reading 
procedure (see -procedure). 



NOTES ON MESSAGE SELECTION 



Messages are selected for printing in a series of steps, each of which filters out 
certain messages according to the control arguments specified. The set of messages at 
each step is any that were left after the previous step. If a control argument was not 
specified, then its corresponding step eliminates no messages. Note that the -expand 
control arguments do NOT select messages, but only affect how their contents are 
displayed 



1) -severity 

2) -excludie 

3) -match 

k) -excl ude__data 

5) -match data 



(e } I mi na te match t ng messages) 
(eliminate non-matching messages) 
(eliminate matching messages) 
(eliminate non-matching messages) 



NOTES ON SEVERITY VALUES 



Severity values in log messages are used to indicate the importance of the message 
being logged, in a general way. Most logs use increasing severity to indicate increasing 
importance, but the actual meaning depends on the log. For the Answering Service 
and Message Coordinator logs, the severities have the following meanings: 

0 *> Message just logged 

1 -> Message logged and printed on a console 

2 => Message logged and printed on a console with bells 

3 Message logged, printed, and the system crashed 
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For the syserr log, the se' 



verities have different meanings: 



0 => Message logged and printed on syserr console 

1 -> Message logged, printed, and the system crashed 

2 => Message logged, printed, and the process writing the 

message is terminated. 

3 Message logged and printed, and console alarm sounded 

if -> Message just logged, or printed if logging mechanism is 
i noperable 

5 => Message just logged, or discarded if it can't be logged 

The severities 20 to 25 are handled just like 0 to 5, but are different to indicate that 
the originating program was writing an access audit message, rather than an 
informative message. 

NOTES ON INNER-RING LOGS 

Some applications create logs in an inner ring that must be read using a special 
interface. The only standard log to do this is the data management system log, and it 
is read when you specify -dms, which supplies both the pathname and the procedure 
name (dm_log_read_). Other applications can provide their own special procedures for 
log reading, in which case you must give the procedure name, using -proc. A log 
read using a reader procedure may enforce additional access requirements as well as 
requiring access to the log itself. In particular, you must have access to the reader 
procedure. 



Name: mos ^edac^summary 

SYNTAX >iS A COMMAND 
mos_edac_summary {-control __args} 
FUNCTION 

scans the syserr log and sunmiarizes MOS EDAC activity in a brief report 
CONTROL ARGUMENTS 
-day_limit N 

sets a threshold of N days that a memory chip can fail before including it in the 
summary. The maximum value for N is 16. 



specifies a relative time (such as *1 hour") used to compute the ending time from 
the starting time. 



-for T 
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-from DT, -fm DT 

specifies the date/ time to start scanning the log. 

-limit N 

sets a threshold of N ED AC errors for a memory chip before including it in the 
summary. 

-mem list 

specifies a list of memories for which information is required (i.e., mem a b c). 
-to D 

specifies the date/ time to stop scanning the log. 
ACCESS REQUIRED 

Read permission is required on the log segments themselves and status permission is | 
required on their containing directories. j 

NOTES 

If -from DT is not specified, the scan starts with the earliest message in the syserr 
log. The ending time may be specified by using -for or -to, but not both. If both 
are omitted, the scan terminates with the last message in the log. All dates and times 
must be in a format acceptable to the convert_date_to_binary_ subroutine, described in 
the Multics Subrouti nes and 110 Modules manual. Order No. AG93. i 



Name: move dir quota 

SYNTAX AS A COMMAND 

move_d I r_quota pathl quota_change1 ... {pathN quota_changeN} 
FUNCTION 

allows a user to move records of directory quota between two directories, one 
immediately inferior to the other. 

ARGUMENTS 

pathi 

is the pathname of a directory. The quota change takes place between this 
directory and its containing directory. A pathi of -wd or -wdir specifies the 
working directory. The star convention cannot be used. 
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quota_changei 

is the number of records to be subtracted from the containing directory's 
directory quota and added to the directory quota on pathi. If this number is 
negative, records are added to the containing directory's directory quota and 
subtracted from the directory quota on pathi. 

ACCESS REQUIRED 

The user must have modify permission on both the directory specified by pathi and 
its containing directory. 

NOTES 

After the change, the directory quota must be greater than or equal to the number of 
records used by directories in pathi unless the change would make the quota zero. 

If the change would make the directory quota on pathi zero, there must be no 
immediately inferior directory with nonzero quota. When the directory quota is 
changed to zero, the records used and the time-record product for pathi is reflected 
up to the superior directory. 

EXAMPLES 

move_d j r_quota >udd>Demo>S!ui th>l_d 5 r 1000 
>udd>Demo>Smi th>l_dir>2_di r -50 

adds 1000 records to the directory quota on >udd>Demo>Smith>l_dir and tracts 1000 
records from the directory quota on >udd>Demo>Smith. It then tracts 50 records 
from the directory quota on >udd>Demo>Smith>l_dir>2_dir and adds 50 records to 
the directory quota on >udd>Demo>Smith>l_dir. 



1 Name: move log segments 

I SYNTAX AS A COMMAND 

I move_l og_segments log-name from-dir to-dir cutoff 
I FUNCTION 

I moves log segments from one directory to another, updating the previous log 
information in the log segment headers so that the log tools (print_sys_log, 
summarize_sys_log) will continue to find the moved log segments. Because it is 
necessary to update log segment headers, this command must be used to move log 
segments; using the move command will cause the segments to become unlocatable. 



2-348 



GB64-00 



move_log_segments 



move_log_segments 



ARGUMENTS | 

log-name i 

is the name of the log whose segments are being moved. This should be the i 

entryname of the first segment in the log (e.g. log, adminjog, dm_system_log, i 

syserr_log); it must not be a pathname. i 

from-dir i 

is the directory in which to look for segments to move. i 

to-dir I 

is the directory to which to move the segments. i 

cutoff I 

is a time value specifying which logs are to be moved. All log segments whose i 

messages are all dated before the cutoff are moved. See the Multics Programmer's i 

Reference Manual, Order No. AG91, for a description of valid time string i 

values. I 

NOTES I 

Old log segments are identified by a timestamp suffix (YYYYMMDD.HHMMSS), j 

which identifies the time of the latest message in the log segment This suffix is i 

tested against the cutoff time, and if it is earlier than the cutoff, the log segment is i 

moved. i 

A history dire-ctory must contain at least one segment; even if the one remaining i 

segment is earlier than the cutoff, it will not be moved, in order to keep the chain j 

correct Thus, a cutoff of the current time can be used to move all but the most i 

recent log segment into another directory. i 

NOTES ON HISTORY DIRECTORIES | 

An arbitrary number of history directories can be maintained; for instance, one for 

the current day's lop, one for the previous week's, and one for the previous month's. 
This allows logs to be distributed onto various storage media, perhaps placing older 
logs on a demountable volume, or even on tape. 

Because log segments are self -identifying (from the suffix), they can be placed on tape | 

and later retrieved selectively into a history directory; the print_sys_log command will | 

still be able to find them if that history directory is in the chain. | 
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I EXAMPLES 

I To move the answering service logs more than a day old into the standard history 

I directory, use the following command: 

I move_log_segments log >scl>as__logs >udd>sa>a>h i story -Iday 

I To trim a log, the date_deleter command can be used on the history directory. Since, 

I however, the DTCM of the log segments in the history directory is the time they 

I were moved there, rather than the actual latest message time in the log, the 

I date_deleter cutoff must be selected to acscount for this. 



Name: mpc data summary 

SYNTAX AS A COMMAND 
mpc__data_summary {list} {-control_args} 
FUNCTION 

scans the syserr log and summarizes the MPC statistics placed there by poH_mpc. 

ARGUMENTS 

list 

is a list of MPC controller names for which the data is to be summarized (i.e., 
mspa mtpb urpa). The MPC controller names must be four characters long, and 
the first three characters must be msp, mtp, or urp. The default list is of all 
MPCs found in the log. 

CONTROL ARGUMENTS 

-all 

reports all MPCs found in the syserr log. 

-brief, -bf 

reports only nonzero device statistics. 

-expand 

expands each syserr log entry that is used for the summary. This may cause much 

/MltOllt 
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-extend, -ext 

extends the output file if it exists. The default is to overwrite the file, 
-for T 

computes the ending time from the starting time, where T is a relative time (such 
as Ihour or Iday). 

-from DT, fm DT 

starts scanning the log at the date/ time given. 

-long, Ig 

reports all device statistics. This is the default 

-mpc list 

displays MPC error data only. 

-output_file {path}, -of {path} 

directs output to the segment specified by path. If path is not given, a default 
segment is used in the working directory and named mpc_data_summary. output. 

-short 

formats output for devices with fewer than 132 columns. The default is based on 
output file type and can be used to override the file output default 

-to DT 

stops scanning the log at the date/ time given. 
ACCESS REQUIRED 

Read permission is required on the log segments themselves, and status permission is 
required on their containing directories. 



Name: ms create, mscr 

SYNTAX AS A COMMAND 

mscr paths 

FUNCTION 

creates a queue message segment with a specified name in a specified directory. 

ARGUMENTS 

paths 

are the pathnames of queues to be created. 
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ACCESS REQUIRED 

The user must have modify and append permission on the directory in which he is 
creating a queue. 

NOTES 

If pathi does not have the ms suffix, it is assumed. 

If the creation of a queue would introduce a duplication of names within the 
directory, and if the old queue has only one name, the user is interrogated as to 
whether he wishes the old queue to be deleted. If the user answers "no", no action is 
taken. If the old queue has multiple names, the conflicting name is removed and a 
message to that effect is issued to the user. 

The extended access placed on a new queue message segment is: 

adros user who created the queue 
ao »*<.SysDaemon.* 

For more information on extended access, see the ms_set_acl command in this 
document. 

EXAMPLES 

mscr special_3 special_2 >daemon_di r_di r>carry_di r>RES. carry 

creates the queues special_3.ms and special_2.ms in the working directory and creates 
the queue RES.carry.ms in the directory >daemon_dir_dir>carry_dir. 



Name: new user 

SYNTAX AS A COMMAND 

new_user$new__user 
or 

new_user$nu 
or 

new__user$nua 
or 

new_user$change Person_id item newvalue 
or 

new_user$cg Person_id Item newvalue 
or 

new_user$cga Person_id item newvalue 
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FUNCTION 

adds or modifies entries in tlie URF and PNT. It is called by master.ec to implement 
the accounting administrator commands that deal with user registration (e.g., register, 
change, chalias). 

Entry: new user 

FUNCTION 

This entry point adds a new person. The dialogue exchanged between the command 
and the user of the command is detailed in the register command. 

Entry: new userSnu 

FUNCTION 

This entry point adds a new person but is less verbose in its prompting. 
Entry: new user$nua 

FUNCTION 

This entry is similar to the new_user$nu entry point but also allows the system 
administrator to specify an alias, password flags, and AIM attributes for the user. 

The dialogue for new_user, new_user$nu, and new_user$n"ua obtains and checks the 
following items for user registration: 

Full name (Last, First I.: title) 

Ma i 1 i ng address 

Programmer number 

Default project 

Password 

Card input Password 
If new_user$nua is called: 
Al ias 

Password flags 
A I M author i zat i on 
Default AIM authorization 
Audit flags 

The commands attempt to generate a site-unique Person_id from the last name, or the 
administrator may specify the Person_id. 

The user is then registered in the URF and PNT and the administrator is asked if 
there are any more users to be added. 
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Typing "stop" at any time aborts the registration of the current user. 

Entry: new userSchange 

FUNCTION 

This entry point supports editing of user registration. 

Entry: new userScg 

FUNCTION 

This entry point is similar to new_user$change but is less verbose. 
Entry: new userScga 



FUNCTION 

This entry is similar to new_user$cg but also allows the changing of user aliases, 
password flags, and AIM attributes. 

ARGUMENTS 

For new_user$change, new_user$cg, and new user_$cga. 
Person_id 

is a Person_id of a registered user. If not specified, the command asks for one. 

item 

may be any one of the following keywords: 

NOTE: The following items marked with an plus-sign (+) can only be changed 
with the new_user$cga entry point. 

addr 

User's mailing address 

+ alias 

User's login alias. An alias can be deleted by using a period (.) as the new 
value. 

+ audit 

AIM audit selectivity flags. This keyword is a character string of the form: 
name 1 { , name2 , . . . , namen} 

where namei is the name of an audit flag. The names and their meanings are 
listed below. 
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priv_op 

controls auditing of privileged operations performed by the process. A 
privileged operation is one performed through use of a privileged gate or 
under previously set AIM privileges. It is recommended that sites 
interested in auditing turn this flag on for all processes except perhaps 
the system daemons. 

admin_op 

controls auditing of administrative operations performed by the process. 
This includes such operations as registration of new users or projects. It 
is recommended that sites interested in auditing should turn this flag on 
for all processes. 

fault 

controls auditing of illegal procedure and access violation faults that can 
indicate an attempt to access protected data. 

small_cc 

controls auditing of covert channel activity that takes place over channels 
with a potential bandwidth of 1-10 bps. 

moderate_cc 

controls auditing of covert channel activity that takes place over channels 
with a potential bandwidth of 10-100 bps. 

<ob ject_ty pe> = < gr an t_level > / <deny_level > 

controls the auditing of specified operations on specified system objects. 
The values of <object_type> can be one of the following: 

fsobj 

specifies that operations to file system objects are to be audited, 
fsattr 

specifies that operations to file system attributes are to be audited. 

rep 

specifies that operations to objects controlled by the Resource Control 
Package are to be audited. 

admin 

specifies that operations to administrative objects (e.g., the PNT) are 
to be audited. 

special 

specifies that operations to special objects are to be audited. 
(Currently, the only special objects are processes.) 

other 

specifies that operations to objects {e.g., mailboxes) controlled by ring 
1 security related subsystems are to be audited. 
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The values that can be assigned to <grant_level> and <deny_level> 
are listed below. 

N 

specifies that no auditing is to take place. 

MA 

specifies thafmodify access" operations are to be audited. Operations 
are audited that attempt to change the access attributes of the object 

M 

specifies that "modify" operations are to be audited. Operations are 
audited that attempt to change the object or the attributes of the 
object. This level of auditing includes the "modify access" operations. 

R 

specifies that "read" operations are to be audited. Operations are 
audited that return information about the contents of the object or 
its attributes/properties. This level of auditing includes the "modify" 
and "modify access" operations. 

The <grant_type>/<deny_type> values are a matched pair. The 
<grant_type> value specifies auditing of successful operations. The 
<deny_type> value specifies auditing of unsuccessful operations. For 
example, the audit flag "fsobj=N/M" specifies that there is to be no 
monitoring of successful operations on file system objects; however, 
all unsuccessful modify operations on file system objects will be 
audited. 

Please note that modify access operations cannot be associated with 
file system objects (fsobj). Instead, modify access operations can be 
specified for file system attributes (fsattr). 

Additional information on auditing, including a more detailed description 
of the operations that are audited on each object type, can be found 
in the Multics System Administration Procedures manual. Order 
No. AK50. 

auth 

AIM authorization is the authorization to be assigned to Person_id. The value 
for auth can be a range of values in the format "min_auth:max_auth," in 
which case the new user is eligible to use any of the authorizations within 
the specified range. Alternatively, the value for auth can be specified as a 
single value. In this case, the system interprets the specified value as a 
maximum authorization value and the minimum authorization value is assumed 
to be system_low. Use the print_auth_names command for a list of valid 
authorization values. 

dfauth 

default AIM authorization 
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+ flags 

The password flags are: 

password 

user has a login password 

network_pw i 
user has a network password | 

trap 

attempts to log in will be logged 

lock 

attempts to log in will be refused 
change 

user can change passwords, default authorization, and default project 
must_change 

user must change login password before logging in 
generate 

user must use -generate_password to change password. 

time_lock=TIME 

password is locked until TIME. 

operator i 
user can use the sign_on command to sign on as an operator. | 

name 

full name (Last First I.: title) 

notes I 
a field for administrator comm.ents. | 

npass (Formerly cpass) 

network password (also used as card input password) 

proj 

default project 

pass 

login password 

progn 

programmer number 

newvalue 

is the new value as a single argument (i.e., enclosed in quotes if it contains 
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blanks). This argument can only be given if item is given. If not specified, the 
command prompts mth the old value and waits for a response. If the new value 
is an empty line, the old value remains unchanged. (The argument may not be 
specified at command level when changing a user's password.) 

NOTES 

Changes are made to both the URF and PNT. 

A password may consist of from one through eight ASCII printing characters including 
backspace, but excluding space and semicolon. "HELP", "help", "quit", and "?" are 
interpreted uniquely by the password processor and are therefore unacceptable as 
password specifications for an interactive login. Entering "quit" terminates the login 
attempt, while "HELP", "help", or "?" results in an explanatory message and repeat of 
the password prompt. 



Name: patch firmware 

SYNTAX AS A COMMAND 

patch_f i rmware path mem addr word 1 .. .word2 .. .word i 
FUNCTION 

patches a segment containing an image of a firmware module for an MPC. 

ARGUMENTS 

path 

is the pathname of the segment containing the firmware. 

mem 

is the memory overlay to patch. This argument can be cs to patch the control 
store overlay, or rw to patch the read /write memory overlay. 

addr 

is the starting address to patch, in hexadecimal, 
wordi 

is a new MPC word, in hexadecimal. All wordi arguments must be in the range 
0-FFFF. At least one wordi argument must be specified. Up to 16 words can be 
patched with one patch_firmware command. 
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NOTES 

This command displays the old and new contents of each firmware word patched, as 
well as the checksum, before the patch is made. You are then asked whether the 
patch is correct The patch is not made unless you answer y^ 

You can retrieve firmware modules from the IF AD tape using the load_tandd_library 
command (described in the Multics Online Test and Diagnostics Manual, Order No. 
AU77). Normally, firmware modules are kept in the sequential file 
>system_library_tandd>tandd_deckfile. 

If the firmware segment to be dumped is for an MSP800 device adapter unit (DAU), 
you must still specify the "cs" or "rw", which does not affect the output because the 
DAU is defined as having only one memory and no control store). In addition, A 
DAU word is defined as containing one eight-bit byte as opposed to the MPC*s two 
eight-bit byte format Even though the DAU memory is one contiguous memory, the 
firmware is still broken into two halves: control store (the first half) and read/write 
(the second half). 



Name: pdt_„copy 

SYNTAX AS A COMMAND 

pdt_copy sat__dir pdt__dir admin__dir 

FUNCTION 

is used by the crank in master.ec to copy the system copies of the SAT and all the 
PDTs into an administrative directory. 

ARGUMENTS 

sat_dir 

is the directory containing the system copy of the SAT (normally >scl). 
pdt_dir 

is the directory containing the system copies of the PDTs (normally >scl>pdt). 
admin_dir 

is the administrative directory into which the SAT and PDTs should be copied 
(normally >udd>SysAdmin>admin>safe_pdts). 

NOTES 

The copies serve as both a backup of the system copies and a summary of the 
continually changing usage figures, from which accounting programs can compute 
month-to-date charges. 
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-stop, -sp 

stops polling for the FNPs specified with the fnpjist argument If no FNPs have 
been specified, polling of all FNPs is stopped. Polling continues to be scheduled 
periodically, even though no FNPs are being polled. 

-start, -sr 

resumes polling for the FNPs specified with the fnpjist argument. If no FNPs 
have been specified, polling of all FNPs is resumed. Note that the next polling 
does not occur immediately, it is performed during the next scheduled polling 
cycle. 
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The command attempts to copy the PDT of every active project in the SAT. If 
unable to copy a particular PDT, it prints an error message and continues. 



Name: poll fnp 

SYNTAX AS A COMMAND 

pel l_f np {fnp_list} {-control_args} 

FUNCTION 

initiates and controls automatic polling of FNPs. Polling consists of reading error 
statistics from the FNP memory and logging them in either the syserr log or a file. 
This command sets up timers and event, call handlers within the process. Once 
initiated, FNP polling is performed periodically, independent of whatever else is going 
on in the process. This command is normally used by the initializer or a daemon. 

ARGUMENTS 

fnp_list 

is a list of the FNP names to be polled. If no names are listed, all FNPs are 
polled. 

CONTROL ARGUMENTS 

-log 

writes statistical information to the syserr log. This is the default Access to the 
hphcs_ gate is required. 

-output_file path, -of path 

writes statistical information to the segment specified by path. This control 
argument can be used in conjunction with -log. 

-time N, -tm N 

specifies the polling interval in minutes. The default polling interval is 15 
minutes. 

-debug, db 

prints extra debugging information each time polling is performed. 

The following control arguments modify the polling already in process and cannot 
be used on the initial invocation of the poILfnp conmiand. 
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-finish 

schedules the last polling cycle immediately. Once this cycle completes, polling is 
disabled, and a new poll_fnp command is required to start it again. To stop 
polling without performing one last cycle, use both -stop and -finish. 

NOTES 

If polling of an individual FNP fails three consecutive times, polling of that FNP is 
stopped. If three consecutive scheduled polling cycles are missed because a previous 
cycle did not complete, an automatic finish operation is performed, and no further 
cycles are scheduled. 

Polling of FNPs has no effect on the users of devices connected to the FNP. 



Name: poll mos memory 

SYNTAX AS A COMMAND 
pol l_inos_memory 
FUNCTION 

reads the maintenance register of each memory on the system and prints information 
about these registers on your terminal. In addition, if the maintenance register 
indicates that an EDAC error has occurred, it is logged in the syserr log. 

ACCESS REQUIRED 

You must have re access to phcs_ to use this command. 
NOTES 

This command should be used with care on systems that have core memories. Unless 
the TEST/NORMAL switch on the maintenance panel of the memory (not controller) 
is set to TEST, the result of reading the maintenance register is undefined, and 
spurious errors may be logged. 



2-361 



GB64-00 



poll_mpc 



poll_mpc 



Name: poll mpc 

SYNTAX AS A COMMAND 

pon_mpc {mpc_list} {-control_args} 

FUNCTION 

initiates and controls automatic polling of MFCs. Polling consists of reading statistics 
on device usage and errors from the MPC memory and logging it in either the syserr 
log or a file. If an error condition is detected, a message is entered in the syserr_log 
with a code of 3. This sounds the bootload console alarm and prints the message in 
the bootload console log on a normally configured system. This command sets up 
timers and event call handlers within the process. Once initiated, MPC polling is 
performed periodically, independent of whatever else is going on in the process. This 
command is used by the initializer or a daemon; Utility.SysDaemon is recommended. 

ARGUMENTS 

-debug, -db 

prints extra debugging information each time polling is performed. 
mpc_list 

is a list of the names of the tape or disk MFCs to be polled, if no names are 
listed, all tape and disk controllers are polled. 

CONTROL ARGUMENTS 

-log 

writes statistical information to the syserr log. Access to the hphcs_ gate is 
required. This is the default. 

-output_file path, -of path 

writes statistical information to the segment specified by path. This report is the 
same as the one generated by the -stat control argument of the dump_mpc 
command. This control argument can be used in conjunction with -log. 

-time N, -tm N 

specifies the polling interval in minutes. The default polling interval is 15 
minutes. 

The following control arguments modify the polling already in process and cannot be 
used on the initial invocation of the poll_mpc command. 

-finish 

schedules the last polling cycle immediately. Once this cycle completes, polling is 
disabled, and a new poll_mpc command is required to start it again. To stop 
polling without performing one last cycle, use both -stop and -finish. 



2-362 



GB64-00 



polLmpc 



post_purge_meters 



-start, -sr 

resumes polling for the MFCs specified with the mpc_list argument. If no MFCs 
have been specified, polling of all MFCs is resumed. Note that the next polling 
does not occur immediately; it is performed during the next scheduled polling 
cycle. 

-stop, -sp 

stops polling for the MFCs specified with the mpcjist argument. If no MFCs 
have been specified, polling of all MFCs is stopped. Polling continues to be 
scheduled periodically, even though no MFCs are being polled. 

NOTES 

If polling of an individual MFC fails three consecutive times, either because it cannot 
be attached or because of I/O errors, polling of that MPC is stopped. If three 
consecutive scheduled polling cycles are missed because a previous cycle did not 
complete, an automatic finish operation is performed, and no further cycles are 
scheduled. 

Foiling of MFCs has no effect on the users of devices connected to the MFC. 



Name: post purge meters, ppm 

SYNTAX AS A COMMAND 
ppm {-control__arg} 
FUNCTION 

displays information collected at post purge time, if post purging is enabled. The 
print_tuning_parameters and work_class_meters commands (described later in this 
section) are used to determine which work classes, if any, are being post purged. 

CONTROL ARGUMENTS 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 
the last call with -reset specified. If -reset has never been given in a process, it 
is equivalent to having been specified at system initialization time. 

-report_reset, -rr 

generates a full report and then performs the reset operation. 

ACCESS REQUIRED 

This command requires access to phcs_ or metering_gate_. 
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NOTES 

If the post_purge_melers command is given with no control argument, it prints a full 
report. 

The following is a brief description of each of the variables printed out by the 
post_purge_meters command. 

Post purge time 

is the average CPU time per post purge call. 

Ave list size 

is the average number of page fault entries found in the per-process page trace 
list at post purge time. 

Ave working set 

is the average estimated working set. The current estimated working set for each 
process is computed by the following formula: 

working set = work i ng_set__f actor * raw_work i ng_set 
+ work i ng_set_addend 

The raw working set is estimated by page control at post purge time. 

Working set factor 

is the current value of the wsf tuning parameter, and can be changed by the 

change_tuning_parameters command. Increasing the value tends to reduce page 

thrashing, but may increase multiprogramming idle. Etecreasing the value has the 
opposite effects. 

Working set addend 

is the current value of the wsa tuning parameter, and can be changed by the 
change_tuning_parameters command. Increasing and decreasing this value has the 
same effects as noted above. 

Thrashing percentage 

is the percentage of page faults that were taken on pages faulted earlier in 
quantum. 

Ave post in main memory 

is the average number of entries in the trace list for which the page was still in 
main memory at post purge time, and the ratio of incore pages to faulted pages 
expressed as a percentage. 
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EXAMPLES 



The following is an example of the information printed when the post_purge_meters 
command is invoked with no control argument 



Total metering time 

Post purge time 
Ave list s i ze 
Ave work i ng set 
Working set factor 
Working set addend 
Thrashing percentage 
Ave post in core 



12:43:11 



3.14 msec. (0.46% of system) 
39.72 entries 
13.14 pages 

0.50 

0 

12.07 % 

26.16 (65.85 %) 



Name: print ^apt entry, pae 

SYNTAX AS A COMMAND 

pae {identifiers} {-control_args} 

SYNTAX AS AN ACTIVE FUNCTION 

[pae APTE_item] 

FUNCTION 

prints one or more Active Process Table Entries (APTEs). Each APTE can be printed 
in octal form, interpreted form, or both. As an active function, it returns individual 
items from the APTE. 

ARGUMENTS 

identifiers 

can be User_ids, channel names, or process IDs. The three types of identifier are 
distinguished from one another by their format (see "Notes" below). They can be 
preceded by control arguments to eliminate any ambiguity (see "Control Arguments 
for Entry Selection"). 

APTEJtem 

can be the process directory pathname or process termination event channel. 

CONTROL ARGUMENTS FOR ENTRY SELECTION 

-absentee, -as 

selects absentee users. 
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-all, -a 

selects all three process types. (Default) 

-channel CHN, -chn CHN 

selects the user logged in over channel CHN. 

-daemon, -dmn 

selects daemon users. 

-interactive, -ia 

selects interactive users. 

-processjd PID, -pid PID 

selects the specified process. 

-user User_id 

selects the given user. 

CONTROL ARGUMENTS FOR OUTPUT FORMAT 

-brief_display 

prints the heading and only the first line of the interpretation produced by 
-display. 

-display 

prints a header and a four-line interpretation of some of the variables in the 
APTE (see "Notes on Output Format"). (Default) 

-dump 

dumps the selected APTE(s) in octal, 
-long, -Ig 

causes octal dumps (when selected) to be eight words per line. (Default) 
-no_display 

prints the heading, but none of the interpretation. 
-no_dump 

eliminates octal dump of APTEs. (Default) 

-process_dir, -pd 

prints or returns the process directory pathname (see "Notes"). 

-short, -sh 

causes octal dumps (when selected) to be four words per line. 

-term_channei, -tchn 

prints or returns the process termination event channel (see "Notes"). 
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ACCESS REQUIRED 

You need read access to the three user tables (absentee_user_table, answer_table, and 
daemon_user_table) in >scl, as well as access to the gate metering_ring_zero_peek_. 

NOTES 

If you give no process selection arguments, the APTE of the current process is 
printed. 

The type of an identifier not preceded by a control argument is determined as 
follows: if it contains only octal digits, it is a process ID; if it contains any 
uppercase letters, it is a User_id; otherwise, it is a channel name. 

Channel names and User_ids can be star names. User_ids are of thei form 
Person. ProjecL tag. You can omit any of the three components, along with any trailing 
periods. Omitted components are treated as if they had been The presence of a 
tag component restricts the search to the corresponding user table for that user only. 

A channel is a communications channel for an interactive process (e.g., a.h017), an 
absentee slot number for an absentee process {e.g., abs3), or a message coordinator 
source name for a daemon process (e.g., bk, prta). 

If you supply a process ID of six digits or less, it is assumed to be the left half of 
a process ID, which is the octal offset of the APTE. 

When you give mutually exclusive control arguments, the last one on the line from 
each set is used. This allows you to define your own defaults by an abbreviation and 
to override them conveniently by using opposing control arguments on a command 
line. The control arguments -interactive, -absentee, and -daemon are not mutually 
exclusive, but are mutually exclusive with -all. 

NOTES ON OUTPUT FORMAT 

This command prints, for each APTE selected, a heading line, an optional interpretation 
of one to five lines, and an optional octal dump. The contents of the heading and 
interpretation are described here. Fields enclosed in square brackets ( [] ) are omitted 
if they contain null values, such as zero. 

The heading 

Pens .Proj . tag <channel> at <offset> in tc_data >pdd><pdir> 

gives the User_id, communications channel, octal offset of the APTE, and process 
directory name. This line is always printed. 
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Line 1: 

[F:<flags> ][E:<event> ]PI D:<proc_id> TRM:<term channel> 

gives the flag word (omitted if zero or if line four, containing flag names, is printed), 
the event word (omitted if zero), the process ID, and the event channel over which 
this process's termination is signaled. All of these are in octal. This line is printed 
unless you select -no_display. 

The remaining four lines are printed by default, but are suppressed by -brief _display 
or -no_display. 

Line 2: 

<state> for <interval> (since <time>[<date>]) . 
Usage: cpu <sec>; vcpu <sec>; pf <n>. 

gives the process state (blocked, running, etc.) and the time interval since state change 
and the time of state change; the date is printed only if it is different from the 
current date. These are followed by the total real and virtual CPU time used, in 
seconds, and the number of page faults. 

Line 3: 

te/s/i/x: <te> <ts> <ti> <t imax>. [<ips name> pending.] 
[Flags: <flag names>.] 

gives the four scheduling parameters (te, ts, ti, and timax) in seconds of CPU time. 
These parameters are described in the Multics System Mai ntenance Procedures 
manual. Order No. AM81; briefly, they are time eligible, time since scheduled, min 
(time since interaction, timax), and the upper limit on ti. Following these parameters, 
any ips signals pending in the process are printed, as well as the names of any flags 
that are on (except for the "firstsw" flag, which is only printed if it is off, an 
indication that the process has never run). 

Line 4: 

[Alarm in <interval> (at <time>[<date>3 [ (<i nterval> after block)]). 
[CPU monitor in <interval> vcpu sec] 

is omitted unless the process has an alarm timer or a CPU monitor set. If an alarm 
timer is set, its time (and date, if different from the current date) are printed. If the 
process is blocked, the interval between the time of blocking and the alarm timer is 
printed. If a CPU m.onitor is set, the amount of virtual CPU time remaining until it 
goes off is printed. 



2-368 



GB64-00 



print_apt_entry 
Line 5: 

IPC R-Offset: <r-offset>, R-Factor 

gives the R-Offset and R-Factor preprocess 
names. 



print_devices 



<r-f actor> 

values used to create IPC event channel 



Name: prmt__devices 

SYNTAX AS A COMMAND 

pri nt__devices {~control_args} 

FUNCTION 

prints a list of devices for each request type handled by the I/O daemon. Also, the 
driver access name and driver authorization (if any) for each request type are printed. 
An asterisk (*) immediately preceding a device name indicates that the associated 
request type is the default for the device. 

CONTROL ARGVMENTS 

-access_name STR, -an STR 

lists only devices for those request types having a driver access name of STR 
(STR should be of the form Person_id.Project_id). 

-brief, -bf 

suppresses printing of a heading line. 

-dir path 

specifies the absolute pathname of the directory containing the iod_working^tables 
segment If not given, the directory >ddd>idd is assumed. 

-request__type STR, -rqt STR 

lists only devices for the request type specified by STR (e.g., printer, punch). 
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Name: print__disk 
SYNTAX AS A COMMAND 
pr i nt__di sk 
FUNCTION 

prints a report from the information stored in the projfile by charge__disk showing 
each project's disk usage. It is called by the master.ec segment 

NOTES 

One line is- printed for each project 

The segment, projfile, is assumed to be present in the working directory and is an 
implicit input to print_disk. 



Name: print iod__tables 

SYNTAX AS A COMMAND 
pr i nt:_iod_tables path 
FUNCT/ON 

displays the contents of an object segment produced by the iod_tables_compiler 
command. The format of the output corresponds exactly to the source language 
accepted by the iod_tables_compiler command. In fact, if the output of the 
print_iod_tables command is directed to a segment, the resulting segment can be 
translated by the iod_tables_compiler command. 

ARGUMENTS 

path 

is the relative or absolute pathname of the object segment to be displayed. 
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Name: print line ids 

SYNTAX AS A COMMAND 

pr i nt_l ine_ids {-control__args} 

FUNCTION 

prints a list of logical line_ids and their associated communications channel from data 
in the iod_workin&_tables segment 

CONTROL ARGUMENTS 

-brief, -bf 

suppresses printing of a heading line. 

-dir path 

specifies the absolute pathname of the directory containing the iod_working_tables 
segment If not given, the directory >ddd>idd is assumed. 



Name: print meters 

SYNTAX AS A COMMAND 
pr i nt_meters {path} 
FUNCTION 

prepares a system performance report from a data segment containing system metering 
data. The metering data is accumulated by as_meter_ in the stat_seg segment; usually 
this is copied into a temporary segment by copy_as_meters before report preparation. 

ARGUMENTS 

path 

is the pathname of the data segment 
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NOTES 



The report contains long lines and is designed for dprinting (use of the file_output 
command is recommended). The report consists of a paragraph for each bootload. A 
header giving the system name, bootload time, and time of last shutdown or crash, is 
followed by one line per sample. Samples are normally taken at each accounting 
update (every 15 minutes) and at startup and shutdown time. The lines contain the 
following columns: 

Time time of sample 

Units load units 

CP number of CPUs 

Kmem number of 102itK word main memory pages 

MPD number of million (M) word paging device (PD) blocks 

Meter time time since bootload 

CPU time CPU time available during sample interval 

Avg queue average queue length (number of processes in queue) 

Response average response time (seconds) 

Idle total idle time in sample interval 

Zero idle total zero idle time in sample interval 

Avg eligible average number of eligible processes 

K mu memory units charged in thousands 



Name: print pdt 

SYNTAX AS A COMMAND 

print_pdt path {Person_ids} {-control_args} 
FUNCTION 

The print_pdt command prints a listing of a project definition table (PDT). 

ARGUMENTS 

path 

is the pathname of the PDT segment to be printed. If the pdt suffix is not 
given, it is assumed. If the pathname given does not start with a greater-than or 
less-than character, it is interpreted as a project name and the PDT in the 
directory containing PDTs (>scl>pdt) is used. 

Person_ids 

are the Person_ids about whom information is desired. If this argument is 
omitted, information is printed for all users listed in the PDT. 
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CONTROL ARGUMENTS 
-brief, -bf 

prints small amount of information about each user, 

-long, -Ig 

prints all data items in the PDT. 

-no_header, -nhe 

suppresses printing of the header. 

-pmf 

prints the PDT in project master file (PMF) format The file.output command 
(described in the Multics Commands and Active Functions manual. Order No. 
AG92) can be used to place the printed PDT in a segment for daemon printing 
or for subsequent use as a PMF (see "Notes" below). 

NOTES 

If no control arguments are given with this command, all PMF-specifiable attributes 
and the total amount spent are printed. The user must have read access to the PDT; 
usually only project administrators have such access. The following command line is 
recommended to make a PMF from a PDT: 

fo Project_id;print_pdt Project_id -pmf;ro 

See also the proj_usage_report command to get a brief summary of each user's 
resource consumption and the display_account_status command to obtain the charges 
accrued to the account. 



Name: print pnt 

SYNTAX AS A COMMAND 

print__pnt {Person_id} {-control__args} 

FUNCTiON 

prints the contents of a binary person name table (PNT) in a readable form on the 
administrator's terminal. Note that, while portions of the user entry in the PNT are 
stored in encrypted form, any encryption algorithm is susceptible to a sophisticated, 
computer-assisted code-breaking effort Therefore the System Administrator should 
ensure that access to the PNT is as restricted as possible. In general, only the 
SysAdmin and SysDaemon projects should have access to the PNT. 
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ARGUMENTS 
Person_id 

specifies the person whose PNT entry is to be printed. If this argument is 
omitted, the entire PNT is printed. 

CONTROL ARGUMENTS 

-brief 

makes no attempt to access information in the user registration file (URF). 

-f orce_no_password_inf o 

same as -no_password_info, but additionally causes the rejection of the -password_info 
control argument for this invocation of print_pnt. This control argument can be 
used to ensure that limited system administrators cannot obtain password 
information. 

-no_password_inf o 

suppresses the display of information about good or bad passwords and the date 
of password change. The rest of the PNT/ URF entry is displayed. 

-password_info 

displays any information about good or bad passwords and the date of password 
change with the rest of the PNT/ URF entry. (Default) 



Name: print projfile 

SYNTAX AS A COMMAND 
pr int_projf i le {path} 
FUNCT/ON 

displays the contents of the project registration file. 

ARGUMENTS 

path 

is the project file to be listed. If omitted, the command prints the segment 
named projfile in the working directory. 
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Name: print reqfile 

SYNTAX AS A COMMAND 
pr i nt_reqf i le {path} 
FUNCTION 

interprets the requisition file and prints it in a readable form. 

ARGUMENTS 

path 

is the pathname of the segment to be printed. If omitted, the command prints 
the named reqfile segment in the working directory. 



Name: print^ sat 

SYNTAX AS A COMMAND 
print_sat path {Project_id} 
FUNCTION 

prints the contents of a binary system administrator table (SAT) in a readable form 
on the administrator's terminal. 

ARGUMENTS 

path 

is the pathname of the sat to be printed. If the entryname portion of path is 
given without a suffix of sat, the suffix is added (unless the entryname portion is 
simply "sat"). 

Project_id 

specifies the project whose SAT entry is to be printed. If this argument is 
omitted, the entire SAT, including the header, is printed. 

EXAMPLES 

The command: 

print__sat >scl>sat 
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prints the system copy of the SAT, for example: 



Maxusers: 


75; 


Maxuni ts : 


750; 


Maxpr im: 


75; 


Uwt: 


process__overseer_, 10; 


Uwt: 


>system_l i brary_tool s>i od_overseer_, 10; 


Admi n i strator : 


*.SysAdmi n; 


Admi ni strator : 


^.SysDaemon; 


Attr i butes: 


nopreempt, preempting, brief, vinitproc, 




vhomedir, nostartup; 


project id: 


SysDaemon; 


projectd i r : 


>udd>SysDaemon ; 


maxpr im: 


100; 


attr i butes : 


pr imary_l i ne, guaranteed_log i n, anonymous 




nolist, dial ok, multip, daemon. 




v_outer_modu 1 e; 


author i zat i on: 


"17,cl ,c2,c3,cA,c5,c6,c7,c8,c9,clO,cn , 




Cl2,cl3,clit,cl5.cl6,cl7,cl8"; 


r i ng: 


1,5; 


a ] i as: 


sd; 


group: 


System; 


grace: 


2880 


project id: 


SysAdmi n; 


projectd i r : 


>udd>SysAdmi n 


maxpr im: 


100; 


attr ibutes: 


pr imary_l i ne, guaranteed_l og i n , 




anonymous, dialok, multip, v_outer_modu 1 e 


audi t: 


"no_access, ipr_fault, acv_mode, acv_ring 




no_wakeup, sys_priv, saa_ops, mseg"; 


author i zat i on: 


"17,cl ,c2,c3,c4,c5,c6,c7,c8,c9,clO,cl 1 , 




cl2,cl3»cH,cl5,cl6,cl7.clo"; 


r i ng: 


^,5; 


a 1 i as : 


sa; 


group: 


Admi n; 


grace: 


2880 ; 


project id: 


Operator: 


projectd i r : 


>udd>Operator ; 


maxpr im: 


100; 


attr ibutes: 


pr imary__l i ne, guaranteed_logi n. 




anonymous, dialok, v outer module; 


r i ng: 


^.5; 


» 1 : . 
a 1 1 a d • 


op; 


group: 


Other; 


grace: 


2880 ; 


project id: 


HFED; 


projectd i r : 


>udd>HFED; 
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maxpr im: 
attributes: 

r ing: 
a1 las: 
group: 
grace: 

project id: 
projectdi r : 
maxpr im: 
attr ibutes; 

r i ng: 
a1 i as: 
group: 
grace: 

project id: 
projectdi r; 
maxpr im: 
attr i butes; 
r i ng: 
group: 
grace: 



100; 

pr imary_l i ne, guaranteed_l og i n, 
anonymous, dialok, v_outer_modul e; 

hfed; 

Other; 

2880; 

Terminal s; 
>udd>Termi nal s; 
100; 

pr imary__l i ne, guaranteed_login, 
anonymous, dialok, v_outer_modul e; 

te; 

Other; 
2880; 

SysMai nt ; 
>udd>SysMai nt; 
32767; 
anonymous ; 

other; 
2880; 



projectdi r : 
maxpr im: 
attr i butes : 
authorization: 

r i ng : 
al i as: 
group: 
grace: 

project id: 
projectdi r : 
maxpr im: 
attr ibutes: 
r i ng: 
al i as: 
group: 
grace: 



>udd>Daemon; 
32767; 

multip, daemon; 

"17,cl ,c2,c3.cit,c5,c6,c7,c8,c9,clO, 
cll,cl2,cl3,cU,cl5,cl6,cl7,cl8"; 

d; 

System; 
2880; 

TOLTS; 

>udd>TOLTS; 

32767; 

anonvmous. multio; 

tol ts; 
Other; 
2880; 



end; 
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Name: print spooling tape 

SYNTAX AS A COMMAND 

pr i nt__spool i ng_tape prtdim device {-control_args} 

FUNCTION 

directly attaches a printer and prints the contents of a tape written by the spool 
driver. 

ARGUMENTS 
prtdim 

is the literal string "prtdim", which is the name of the standard Multics printer 
I/O module (DIM). 

device 

is the name of the lOM channel for the printer device to use. 

CONTROL ARGUMENTS 
-number N, -nbr N 

begins printing at N where N is the file number of a file on tape. If it is 
omitted, printing begins with the first file on the spooling tape. 

-debug, -db 

turns on audit trace during printing. The default is debug off. 
EXAMPLES 

To print a spooling tape, starting with the third file on the tape, using the standard 
Multics printer I/O module (identified as "prtdim") and the printer (identified as 
"prta"), the operator types: 

pr i nt_spoon ng_tape prtdim prta -nbr 3 
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Then the operator is asked for volume identifiers and spooling limits, as shown below: 

Enter volids and optional file limits: 

The operator types: 

-vol id SPOOL] -files 50 

giving the volid of the spooling tape to be printed (SPOOLl) and a limit of 50 files 
to print before printing is stopped. The I/O module, tape_ansi_, determines whether 
to read the spooling volume at 800 or 1600 bpi density and, from the tape labels, the 
I/O module determines the tape block size and maximum line-length to be printed. 

Next, the operator is requested to mount the first volid and a message is typed on 
the terminal as follows: 

Mounting volume SPOOLl with no write ring. 
Volume mounted on tape_XX. 

As each file on the spooling tape is printed, a message appears on the terminal giving 
the number of the file. This continues until the file limit has been reached or until 
the entire tape has been processed. The spool driver output looks like the following: 

Pr i nti ng F I LE 3 
Printing FILE U 



Printing FILE 50 

Reached end of data for current fileset. 
Taking current volume down. 
Printer detached. 

Processing of spooling tape ended. 

Spooling file count is kS 
Spooling line count is 125^ 

At this point, printing has finished and the operator can logout the process. 
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DESCRIPTION OF THE SPOOLING TAPE 

The spool driver creates either an 800 or 1600 bpi ANSI standard tape (ASCII) with 
D-format (variable length) records of a specified printer line length, that are blocked 
to 8192 characters, unless the interchange option is specified, in which case, the block 
size is 2048 characters and the density is 800 bpi. Each print request constitutes one 
ANSI tape file, which is surrounded by ANSI standard tape labels. The exact format 
of the ANSI tape can be found by referring to Draft Proposed Revision X3L5/419T 
of the American National Standard Institute's ANSI X3.27-1969, "Magnetic Tape Labels 
and File Structure for Information Interchange." Each line (logical record) of the 
request (print file) is preceded by a USA printer carriage control character that directs 
a printer action before the line is printed. These control characters and the 
corresponding Multics spool driver slew functions are listed below. 

USA Spool Driver 

Char Slew Function Printer Action 



D 1 anK 


NL 




One 1 i ne 


spaced 




0 


2(NL) 
3(NL) 




Two 1 i nes spaced 
Three lines spaced 


+ 


CR 




Suppress 


1 i ne space 


1 


FF 




Skip to channel 1 

(top: line 3» any page) 


2 


none 




Skip to 


channel 


2 


3 


none 




Skip to 


channel 


3 


U 


none 




Skip to 


channel 


k 


5 


none 




Skip to 


channel 


5 


6 


none 




Skip to 


channel 


6 


7 


bottom 


inside page 


Skip to channel 
(odd page) 


7 


8 


bo t tofn 


i ne 1 rl« nan» 


(even page) 


8 


9 


none 




Skip to 


channel 


9 


A 


none 




Skip to 


channel 


10 



2-382 



GB64-00 



prini_spooling_tape 



print_sys_log 



B 



none 



Sk i p to channel 1 1 



C 



none 



Skip to channel 12 



Note: The printer action occurs before a line occurs printed. 



Name: print sys log, psi 

SYNTAX AS A COMMAND 

psl {log_sel ector} {-control_args} 

FUNCTION 

prints selected portions of system logs, including the syserr log, answering service log, 
admin logs, message coordinator (daemon) log, and data management logs. Various 
control arguments are used to determine which portions of the log are printed, and 
the format of the output. 

ARGUMENTS 

log_selector 

is the pathname of a log to be printed. The pathname must specify the first 
segm.ent in the log. This argument is incompatible with any of the log selection 
control arguments. 

CONTROL ARGUMENTS FOR LOG SELECTION 



specifies that the admin log is to be printed. The admin commands log is called i 

"admin_log", and is located in the >scl>as_logs directory. This argument is i 

incompatible with any of the other log selection control arguments, or an explicit i 

log pathname. i 

-answering_service, -as i 

specifies that the answering service log is to be printed. The answering service log i 

is called "log", and is located in the >scl>as_logs directory. This argument is i 

incompatible with any of the other log selection control arguments, or an explicit j 

log pathname. | 

-dm_system, -dms 

specifies that the data management system log for the process' current AIM 
authorization is to be printed. The data management log is called "dm_system_log", 
and its location depends on the AIM access class of the log. This argument is 
incompatible with any of the other log selection control arguments, or an explicit 
log pathname. Reading the log requires access to the dm_admin_ gate. 



-admin 
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-mc_log log_name, -mcl log_name 

specifies that the message coordinator (daemon) log named log_name is to be 
printed. All message coordinator logs are located in the >scl>as_logs directory; 
their names depend on the daemon to which they belong. This argument is 
incompatible with any of the other log selection control arguments, or an explicit 
log pathname. 

I -syserr 

I specifies that the syserr log is to be printed. The syserr log is named 

I "syserr_log". The first segment in the log is >sll>syserr_log; there may be a 

I history segment in >sll, and older history segments are in the directory 

I >scl>syserr_log. This argument is incompatible with any of the other log selection 

I control arguments, or an explicit log pathname. 

I CONTROL ARGUMENTS FOR LIMIT SELECTION 

-for time, -for number 

specifies a number of messages to print, or a time interval relative to the starting 
time (specified by -from) in which the messages must be contained. The number 
of messages is the actual number of messages printed, not the number of messages 
examined in the log. This is incompatible with -to and -last 

I -forward, -fwd 

j specifies that the log is to be printed starting with the oldest message selected by 
I other control arguments, and proceed forwards. This is the default. 

I -from time, -fm time, -from number, -fm number 

I specifies that the first message printed is the first message at or after the 

I specified time or sequence number; if -reverse is specified, the first message is 

I the one at or before the specified value. If no -from value is specified, the 

I default is the first message in the log, or the last if -reverse is specified. This is 

I incompatible with -last 

-last number, -It number, -last time, -It time 

specifies that only the last number messages, or the messages since time, are to be 
printed. If a number is specified, it specifies the actual number of messages to 
be printed, not the number of messages examined in the log. This is incompatible 
with -from and -for. 

I -reverse, -rv 

I specifies that the log is to be printed starting with the most recent message 
I selected by other control arguments, and proceed backwards. 

-to time, -to number 

specifies the last message to be printed, either by message time or sequence 
number. If not specified, the default is all the remaining messages in the log. 
This is incompatible with -for. 
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CONTROL ARGUMENTS FOR MESSAGE SELECTION | 

-alUdata^classes, -adc 

specifies that all messages, regardless of data class, are to be processed. This 
control argument cancels the effect of any preceding -match_data_class or 
exclude_data_class control argument This is the default 

-all_severities, -asv i 
specifies that messages of all severities are printed. This cancels the effect of any i 
previous -severity control arguments. This is the default i 

-all_text -atxt i 

specifies that all messages, regardless of text contents, are to be processed. This i 

control argument cancels the effect of any preceding -match or -exclude control i 

argument This is the default i 

-exclude_data_class, CLASS, -exdc CLASS j 
specifies that no messages with the specified data class are to be processed. i 

-exclude STR-1 ... STR-n, -ex STR-1 ... STR-n i 

specifies that no message whose text contains one of the specified strings (STR-1 { 

to STR-n) is processed. A string is interpretol either as a text string, which must i 

be an exact substring of the message text or, if surrounded by slashes, as a i 

regular expression to match against the message text See the "Notes on String i 

Matching" section below for details. i 

—match data class CLA.SS, — mdc CLA.SS • 
specifies that only messages with the specified data class are processed. See "Notes i 
on Data Classes," below. i 

-match STR-1 ... STR-n 

specifies that only messages whose text contains one of the specified strings 
(STR-1 to STR-n) are processed. The strings are processed as for -exclude. 

-no_match_exclude, -nmx j 
specifies that all log messages are to be processed, regardless of text contents, | 
cancelling the effect of any preceding -match or -exclude. This is the default | 

-severity SEV-1 ... SEV-n, -sv SEV-1 ... SEV-n 

specifies that only messages of the specified severity (severities) are processed. The 
severity values (SEV-1 to SEV-n) may either be decimal integers, or ranges 
consisting of a pair decimal integers separated by a colon ("20:29"). If multiple 
severities are specified, or the -severity control argument is specified more than 
once, all messages with any of those severities are printed. A severity value must 
be between -100 and 100, See the "Notes on Severity Values" below for details. 
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I CONTROL ARGUMENTS FOR MESSAGE EXPANSION 
-all_data, -ad 

specifies that all messages with binary data are to be processed. This control 
argument cancels the effect of any preceding -match_data or -exclude_data 
control argumenL This is the default. 

-exclude_data STR-1 ... STR-n, -exd STR-1 ... STR-n 

specifies that no messages whose interpreted expanded data contains one of the 
specified strings (STR~1 to STR-n) is processed. The strings are processed as for 
-exclude. Note: this control argument merely matches against the textual 
interpretation of the expanded data; if this interpretation is to be displayed as 
well, the -interpret control argument must also be specified. 

-expand {CLASS-1 ... CLASS-n} 

specifies that binary data is to be expanded and displayed along with the message 
text, for the selected messages. If a data class value (CLASS-1 to CLASS-n) is 
specified, only binary data of the specified classes will be expanded; otherwise, all 
selected messages with binary data will be expanded. The type of expansion 
depends on whether the -octal or -interpret control arguments are also specified. 
See the "Notes on Data Classes" section below for details. By default, no 
messages are expanded. 

j "interpret, -int 

I specifies that the binary data in expanded messages is to be displayed as 
I interpreted text, by calling the appropriate expand_XXX_msg_ program for the 
I data class of the message. If the -octal control argument is also specified, the 
I binary data is displayed both in interpreted form and as octal data. This is the 
I default 

-match_data STR-1 ... STR-n, -md STR-1 ... STR-n 

specifies that only messages whose interpreted expanded data contains one of the 
specified strings (STR-1 to STR-n) are processed. The strings are processed as for 
-exclude. Note: this control argument merely matches against the textual 
interpretation of the expanded data; if this interpretation is to be displayed as 
well, the -interpret control argument must also be specified. 

-no_expand, -nex 

specifies that no messages are to be displayed with binary data expanded. This 
cancels the effect of any previous -expand control arguments. By default, no 
messages are expanded. 

-octal, -oc 

specifies that the binary data in expanded messages is to be displayed in octal, 
rather than, or in addition to, the interpreted representation. If both octal and 
interpreted representations are desired, both the -octal and -interpret control 
arguments must be supplied. 
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CONTROL ARGUMENTS FOR MESSAGE FORMAT 

-continuation_indent N, -ci N 

specifies that all messages are to be formatted for printing with continuation lines 
prefixed by N spaces, or, if the keyword "standard" or "std" is used in place of 
a number, with the continuation lines indented sufficiently to line up under the 
first character of the text of the message. The value of N must be between zero 
and fifty. By default, continuation lines are indented to the "standard" 
indentation. 

-date_format FORMAT.STRING, -dfmt FORMAT_STRING 

specifies a date/ time format string (see time_format.gi.info or the Multics 
Programmer's Reference Manual, Order No. AG91) to be used when formatting 
the date when successive messages are printed with different dates. The date 
string is printed on a line entirely by itself, preceded by a blank line. If the 
date format string is blank, no date separators will be printed; this should be 
used if a -time_format string is specified that includes the date as well. The 
default date string is "'^9999yc-'^my-'^dm '^da '^za", which prints as (for example) 
"1984-10-31 Wed est". 

By specifying null strings for date, time, and number formats, the log can be 
printed and saved, so that it can be compared to another log script later, without 
spurious mis-compares because the times and sequence numbers do not match. 

-duplicates, -dup 

inhibits the printing of "=" messages for messages whose text is the same as the 
previous message printed. All messages are printed exactly as they appear in the 
log. 

-indent N, -ind N 

specifies that all messages are to be formatted for printing prefixed with N 
spaces. The value of N must be between zero and fifty. The indentation is 
printed before any data associated with the message, including the message prefix. 
By default, there is no indentation. 

-line_length N, -11 N 

specifies the line length used when formatting message text and data for printing. 
The value (N) must be between 25 and 500. By default, it is the line length 
associated with the user_output I/O switch, or, if none (as for an absentee), it is 
132 (for line printer output). 

-no_dupiicates, -ndup 

prints "==" for messages whose text is the same as the previous message printed. 
This is the default 

-number_format IOA_STRING, -nfmt IOA_STRING 

specifies an ioa_ string to be used when printing the sequence number for the 
message. If the string is null, no sequence number is printed with the message. 
The default is "^7d". (See the Multics Subroutines and 110 Modules manual. 
Order No. AG93 for a description of ioa_control strings). 
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-prefix STRING, -pfx STRING 

Specifies that all messages are to be formatted with the specified string as a 
prefix. This prefix appears after the indentation (if any was specified). The 
prefix must explicitly include trailing spaces, if any are desired to separate the 
prefix from the message texL By default, there is no prefix. 

-time_format FORMAT.STRING, -tfmt FORMAT.STRING 

specifies a date/ time format string (see time_format.gi.info or the Multics 
Programmer's Reference Manual, Order No. AG91) to be used when formatting 
the message time portion of the message. If the string is null, no time is printed 
with the messages. The default time format is "iso_time", which prints as (for 
example) "23:21:59". 

I MISCELLANEOUS CONTROL ARGUMENTS 

I -data_class, -de 

I specifies that the data class of each message is to be printed, 
-header, -he 

specifies that a header is to be printed giving the times and sequence numbers of 
the first and last messages proce^ed. (Default) 

I -no_data_class, -ndc 

I specifies that the data class of each message is not to be printed. This is the 
j default 

I -no_header, -nhe 

I specifies that no header is to be printed. 

-no_process_id, -npid 

specifies that the processed stored with each message is not to be printed. This 
is the default 

I -output_switch NAME, -osw NAME 

I specifies that the messages are to be written on the named I/O switch. The 
[ default is user_outpuL 

-procedure NAME, -proc NAME 

specifies that entrypoints in the procedure called NAME are to be used instead of 
entrypoints in log_read_ to read the log. This is used to read logs protected by 
inner-ring subsystems, where the inner-ring subsystem provides a replacement 
log-reading procedure. See "Access Required" section, below. 

I -processed, -pid 

I specifies that the process_id stored with each message is to be printed. 
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NOTES ON STRING MATCHING 

The strings specified by -match and -exclude, or by -niatch_data and -exclude_data, 
are processed in sequence. An arbitrary number of strings may follow any of those 
control arguments, and each string will be treated as if it was preceded by another 
instance of the control argument, except that any string beginning with a hyphen and 
not immediately following one of the match /exclude control arguments is treated as a 
new control argument, and no more strings are picked up until the next match /exclude 
argument 

A string may be either a text string, in which case it is tested simply to see whether 
it is a substring in the message, or it may be a regular expression, which is matched 
against the message. A string will be interpreted as a regular expression if it begins 
and ends with "/" characters. 

Each log message is processed against the set of strings, matching its text (or data) to 
see if it contains the string. There are two simple cases: only match strings, and only 
exclude strings. In the case of only match strings, any log message that matches any 
of the strings will be printed. In the case of only exclude strings, a log message will 
be printed only if it matches none of the strings. 

The more complicated case where match and exclude strings are mixed is handled as 
follows: test the message against each string in turn. If the message matches, and the 
string is a "-match" string, the "print-this-message" flag is set on. If the message 
matches, and the string is a "-exclude" string, the flag is set off. Otherwise, the flag 
is unaffected. The flag's initial value is on if the first string was a "-exclude" string, 
and off if the first string was a "-match" string. 

NOTES ON DATA CLASSES 

A data class is a short string (1 to 16 characters) stored with any message that 
contains binary data, and is used to identify the expander procedure used to expand 
the data into its interpreted textual form. The data class is specified when the 
message is placed into the log. 

The data class "syserr" identifies an old-style syserr log message. The "syserr binary" 
code (see syserr_binary_defs.incl.pll for a list) is the first word of the data in the 
message; the remaining words of data are the real binary syserr data. 

ACCESS REQUIRED 

For all except inner-ring logs, read permission is rcQiiired on the log segments 
themselves, and status permission is required on their containing directories. If an 
access error is encountered searching for older history logs, the search is stopped at 
that point, and no further history will be available. For the logs selected by control 
arguments, the control argument descriptions list the standard history directories for 
the logs. 
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For inner-ring logs (the data management system log is the only standard inner-ring 

log), access to the logs is required, as is access to the gate used by the log-reading 
procedure (see -procedure). 

NOTES ON MESSAGE SELECTION 



Messages are selected for printing in a series of steps, each of which filters out 
certain messages according to the control arguments specified. The set of messages at 
each step is any that were left after the previous step. If a control argument was not 
specified, then its corresponding step eliminates no messages. Note that the -expand 
control arguments do NOT select messages, but only affect how their contents are 
displayed 



EXAMPLES 



1) -to 

2) -from 

3) -for TIME 
k) -last TIME 

5) -severity 

6) -exclude 

7) -match 

8) -exclude_dat3 

9) -match_data 

10) -for NUMBER 

11) -last NUMBER 



(stop looking after specified message) 

(stop looking before specified number) 

(stop looking after specified time) 

(stop looking before specified time) 

(eliminate matching messages) 
(eliminate non-matching messages) 
(eliminate matching messages) 
(eliminate non-matching messages) 
(stop after NUMBER are printed) 
(stop after NUMBER are printed) 



Severity values in log messages are used to indicate the importance of the message 
being logged, in a general way. Most logs use increasing severity to indicate increasing 
importance, but the actual meaning depends on the log. For the Answering Service 
and Message Coordinator logs, the severities have the following meanings: 



0 => Message just logged 

1 => Message logged and printed on a console 

2 => Message logged and printed on a console with bells 

3 => Message logged, printed, and the system crashed 

For the syserr log, the severities have different meanings: 

0 => Message logged and printed on syserr console 

1 => Message logged, printed, and the system crashed 

2 => Message logged, printed, and the process writing the 

message is terminated. 

3 — ^ Message logged and printed, and console alarm sounded 

k -> Message just logged, or printed if logging mechanism is 
i noperab 1 e 

5 => Message just logged, or discarded if it can't be logged 
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The severities 20 to 25 are handled just like 0 to 5, but are different to indicate that 
the originating program was writing an access audit message, rather than just an 
informative message. 

NOTES ON INNER-RING LOGS 

Some applications create logs in an inner ring that must be read using a special 
interface. The only standard log to do this is the Data Management system log, and it 
is read by specifying the -dm_system control argument which "supplies both the 
pathname and the procedure name (dm_log_read_). Other applications may provide 
their own special procedures for log reading, in which case both the log pathname and 
the procedure name must be supplied explicitly via the -pathname and -procedure 
control arguments. Note that a log read using a reader procedure may enforce 
additional access requirements as well as requiring access to the log itself. In 
particular, the user must have access to the reader procedure. 

COMPATIBILITY FEATURES 

The following control arguments are accepted for compatibility with the old 
print_syserr_log and print_log commands: 

-action is equivalent to -severity 

-next is equivalent to -for 

-debug, -db is equivalent to -duplicates 

The effect of print_syserr_log's -class argument can be achieved by supplying a range 
to the -severity argument: "-class 2" is replaced by "-severity 20:29". 



Name: print tuning parameters, ptp 

SYNTAX AS A COMMAND 

ptp {name! ... nameN} {-control_args} 

FUNCTION 

prints the current values of various tuning parameters within the system. The values 
of m.ost of these tuning parameters can be changed by using the change_tuning_parameters 
command described earlier in this section. 

ARGUMENTS 

namei 

is the name of a tuning parameter whose value is to be printed. It can be either 
the long name or the short name of the parameter. If no names are supplied, all 
tuning parameters that can be changed while the system is running are printed. 
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CONTROL ARGUMENTS 
-all, -a 

if no names are specified, prints all tuning parameters, including those that are 
"special" and not alterable while the system is running (e.g., max_max_eligible, 
which can only be changed by means of a bootload). 

-long, -Ig 

lists the short and long names of the parameter(s),as well as a pointer to the 
location of the tuning parameters in ring zero. 

-short, -sh 

prints only the long name and the value of the parameter(s) (default). 
ACCESS REQUIRED 

This command requires access to metering_gate_. 
NOTES 

See the Multics System Maintenance Procedures manual. Order No. AM81, for 
explanations of the tuning parameters. 

EXAMPLES 

The following is an example of the information printed when the print_tuning_parameters 
command is invoked: (See Appendix A for a representation of the contents of the 
configuration deck used to create the system from which the metering sample was 
taken.) 



Current system tuning parameters: 


tef i rst 


0.5 seconds 


tel ast 


1 . seconds 


t imax 


8. seconds 


pr i or i ty_sched_i nc 


80. seconds 


m i n_e 1 i g i b 1 e 


2. 


max_el i g i bl e 


20. 


max_batch__e1 i g 


0 


work i ng_set_f actor 


0.5 


work 1 ng__set_addend 


0 


dead 1 i ne__mode 


off 


i nt_q_enab1 ed 


on 


r»r»ct nnrn(= 


off 


pr e_emp t__samp 1 e_t i me 


0.04 seconds 


gp_at__not i f y 


off 


gp_at_pt 1 not i f y 


off 


process__i ni ti al_quantum 


2. seconds 


qui t_pr lor 1 ty 


0. 


not i f y_t imeout__i nterval 


30. seconds 



2-392 



GB64-00 



print_tuning_parameters 



priv_move_quota 



not i f y_t imeout__sever i ty 
wr i te_l imi t 
gv__i ntegrat i on 



3 

335 

4. seconds 
on 

0. seconds 
0.005 seconds 
on 



real t ime__i o_pr ior i ty 
rea 1 1 i me_i o_dead 1 1 ne 
real t ime_io_quantum 
dirlock writebehind 



Name: print urf 

SYNTAX AS A COMMAND 
print_urf {Person_id} 
FUNCTION 

prints the name, title, address, programmer number, project, and User_id of each entry 
in Uie user registration file (URF). 

ARGUMENTS 



is the person v/hose entry is to be printed. If omitted, all entries will be printed. 



Name: priv move quota 

SYNTAX AS A COMMAND 

pr i v__move_quota pathl quota_changel {... pathN quota_changeN} 
FUNCT/ON 

moves records of quota between two directories (one immediately inferior to the other) 
regardless of the authorization of the process. 

This command is identical to the standard move_quota command except that directory 
system privileges are turned on while quota is being moved. The priv_move_quota 
command is needed only if the site is using the AIM access controls. 



Person_id 
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ARGUMENTS 
pathi 

is the pathname of a directory branch. The quota change takes place between this 
branch and its containing directory. The working directory may be specified by 
-wd. The star convention may not be used. 

quota_changei 

is the number of storage records to be subtracted from the containing directory 
quota and added to the quota on pathi. If this number is negative, the number 
of records is added to the containing directory quota and subtracted from the 
quota on pathi. 

ACCESS REQUIRED 

The user must have "re" access to system_privilege_ gate and must have modify 
permission specified on the ACL of both pathi and its containing directory. 



Name: process id 

SYNTAX AS A COMMAND 

process__id {identifiers} {-control_args} 

SYNTAX AS AN ACTIVE FUNCTION 

[process_id {identifiers} {-control__args} ] 

FUNCTION 

prints or returns a process id of a specified process, in the form of a 12-digit octal 
number. 

ARGUMENTS 

identifiers 

can be Userjds, channel names, or APTE offsets. The three types of identifier 
are distinguished from one another by their format (see "Notes" below). Two of 
the types can be preceded by a control argument to eliminate any ambiguity (see 
"Control Arguments"). If no identifier is given, the process ID of the current 
process is used. 

CONTROL ARGUMENTS 

-absentee, -as 

selects absentee users. 
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-all, -a 

selects all three process types. This is the default 

-channel CHN, -chn CHN 

selects the user logged in over channel CHN, 

-daemon, -dmn 

selects daemon users. 

-interactive, -ia 

selects interactive users. 

-multiple 

allows more than one process to be selected. Their process ids are returned, 
separated by spaces. This is the default if more than one identifier is given. 

-single 

requires that the arguments select exactly one process. This is the default, unless 
more than one identifier is given. 

-user User_id 

selects this user. 

NOTES 

Unless the -multiple control argument is given, or more than one identifier is given, 
it is an error if the arguments do not select exactly one process. 

The type of an identifier not preceded by a control argument is determined as 
follows: if it contains only octal digits, it is an APTE offset; if it contains any upper 
case letters, it is a User_id; otherwise, it is a channel name. Channel names and 
User_ids can be starnames. User_ids are of the form Person.Project.tag. Any of the 
three components can be omitted, along with any trailing periods. Omitted components 
are treated as if they had been The presence of a tag component restricts the 
search to the corresponding user table for that user only. 

A channel is a communications channel for an interactive process (e.g., a.h017), an 
absentee slot number for an absentee process (e.g., abs3), or a message coordinator 
source name for a daemon process (e.g., bk, prta). 

The APTE offset is given as a four- to six-digit octal number (see the 
print_apt_entry command). 

The -absentee, -interactive, and -daemon control arguments can be given in any 
combination. The default, when User_id with a tag and none of these arguments is 
given is to search all three user tables. 
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ACCESS REQUIRED 

Read access to the three user tables (absentee_user_table, answer_table, and 
daemon_user_table) in >scl is required, as well as access to the gate 
metering_ring_zero_peek_ (the latter only if an APTE offset is given as an identifier). 
None of the above access is required when no identifier is given and the ID of the 
current process is returned. 

EXAMPLES 

! [process__id *.SysAdmin -as] 

prints the process_id of the single absentee process from the SysAdmin project. The 
example is in error if there is more than one absentee process from that project. 



Name: proj usage report, pur 

SYNTAX AS A COMMAND 

pur {Project_id} {-contro1_args} 

FUNCTION 

prints a project usage report for the current billing period. 

ARGUMENTS 

Project_id 

is the Project_id of the project. If this argument is not given, the project under 
which the project administrator is currently logged in is assumed. 

CONTROL ARGUMENTS 

-brief, -bf 

prints reports in one short line per user. 

-long, -Ig 

prints detailed information about per shift, per absentee, per device, and I/O 
daemon queue usage. 

-no_header, -nhe 

suppresses printing of the header. 

-pathname path, -pn path 

is the pathname of a PDT. The pdt suffix must be given. This control argument 
is used to print a PDT not currently being used by the answering service. If this 
control argument is specified, the Project_id argument may not be given. 



2-396 



GB64-00 



proj_iisage_repon proj_iisage_report 



-reverse, -rev 

reverses the order of the sort. 

-sort XX 

sorts output according to XX, where XX can be the string: 

name 
usage 
rem 
limit 

f ract i on_used 

to specify users' names, usage, remainder, limits, or entries in order of ratio 
between usage and limit. Only one string may be specified. The default prints 
the PDT as is. 

-total, -tt 

does not print a line for each user; rather prints a totals line (plus any other 
lines specified by other arguments). 

-user Person_id 

prints information on only the user specified by Person_id. 

ACCESS REQUIRED 

The user must have read access on the PDT; usually only project administrators have 
such acc^. 

NOTES 

If neither the -brief nor -long control argument is given, the report printed contains 
one detail summary line for each user. 

See also the print_pdt command to get more detailed information about each user and 

the display_account_status command to obtain a summary of the charges accrued to 
the project 
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I Name: read early dump tape, redt 

I SYNTAX AS A COMMAND 

I redt reel_num -control_args 

I FUNCTION 

reads the contents of a tape produced by the early dump facility of BCE and 
produces a standard format dump in a specified directory. 

I ARGUMENTS 

I reel_num 

I is the reel number of the early dump tape. This argument may by placed 
I anywhere on the command line. 

I CONTROL ARGUMENTS 

-dump N 

generates a dump with a dump number of N. This control argument is required. 
-dump_dir directory 

places the dump into the specified directory. The default is to place the dump 
into >dumps. 

-density N, -den N 

sets the tape density to N. Unless site modified, early dump tapes are written at 
1600, which is the default. 

-ring, -rg 

mounts the tape with a write ring. 



Name: reclassify dir 

SYNTAX AS A COMMAND 

reel ass i fy_di r path {accessed ass} 

FUNCT/ON 

changes the AIM access class of a directory and all immediately inferior segments. 
The access class of inferior directories and system segments (in ring 1) is not changed. 

The reclassify_dir command is needed only if the site is using the AIM access 
controls. 
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ARGUMENTS 
path 

is the pathname of the directory to be reclassified, 
access.class 

is the access class to be assigned to the directory and its segments. Use the 
print_auth_names command for a list of valid access class values. See the Multics 
Programmer's Reference Manual, Order No. AG91, for a detailed descussion of 
AIM access controls. 

ACCESS REQUIRED 

The user must have access to the system_privilege_gate to use this command. 
Additionally, the user must have modify permission specified on the acl of "path" and 
its containing directory. However, the reclassification is performed without checking 
the validation level of the process. Therefore, reclassification of all immediately 
inferior segments to "path" may be performed from the user ring regardless of the 
ring brackets of the segments. 

NOTES 

If the access_class argument is omitted, the current access class of path is assumed, 
and only the immediately inferior segments are reclassified. 

If the new access_class is not greater than or equal to the access class of the 
containing directory of path, the reclassification is refused. If the new access_class 
would make the access class of a branch in path inconsistent, the branch is set 
security-out-of -service. If the new access_class would make a directory in path 
upgraded, but with 0 quota, this directory is set security-out-of -service. If the new 
access_class would make path upgraded, but with no terminal quota, the command 
fails, indicating that terminal quota is required for an upgraded directory. 

This command corrects some of the possible inconsistencies that could cause the 
directory to be marked security-out-of -service by the salvager. 



Name: reclassify si^ 

SYNTAX AS A COMMAND 
reel ass I f y_seg path 
FUNCTION 

sets the access class of a segment equal to the access class of its containing directory. 
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The reclassify_seg command is needed only if the site is using the AIM access 
controls. 

ARGUMENTS 

path 

is the pathname of the segment to be reclassified. 
ACCESS REQUIRED 

The user must have access to the system_privilege _gate to use this command. 
Additionally, the user must have modify permission specified on the ACL of the 
containing directory. However, the reclassification is performed without checking the 
validation level of the process. Therefore, reclassification of ring 1 segments may be 
performed from the user ring. 

NOTES 

This command corrects one of the possible inconsistencies that could cause a directory 
to be marked security-out-of -service by the salvager. However, the directory is not 
placed back into service by this command. (See the reset_soos command for that 
function.) 

When the specified pathname is a ring 1 system segment (i.e., a segment whose access 
class is greater than that of its containing directory), this command makes it a ring 1 
normal segment (i.e., a segment whose access class is equal to that of its containing 
directory). 



Name: reclassify sys seg 

SYNTAX AS A COMMAND 

red ass i f y_sys__seg path {accessed ass} 

FUNCT/ON 

changes the access class of a ring 1 system segment or converts a ring 1 normal 
segment to/ from a system segment. A ring 1 system segment is a segment whose 
access class is greater than that of its containing directory, e.g,, message segments such 
as those used for daemon queues and user mailboxes; a ring 1 normal segment is a 
segment whose access class is equal to that of it^ containing directory. 

The reclassify_sys_seg command is needed only if the site is using the AIM access 
controls. 
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ARGUMENTS 
path 

is the pathname of the segment to be reclassified. 

access_class 

is the access class (sensitivity level and category) to be assigned to the segment. 
Use the print_auth_names command for a list of valid access class values. See the 
Multics Programmer's Reference Manual, Order No. AG91, for a detailed 
discussion of the AIM mechanism. 

ACCESS REQUIRED 

The user must have access to the system_privilege_gate to use the command. 
Additionally, the user must have modify permission specified on the acl of the 
containing directory. However, the reclassification is performed without checking the 
validation level of the process. Therefore, reclassification of ring 1 segments may be 
performed from the user ring. 

NOTES 

If the segment is to become a normal segment, the access_class argument must be 

omitted. A specified access_class argument must be greater than the access_class of the 
containing directory. 

^ I 

Name: reconfigure | 

SYNTAX AS A COMMAND | 

reconfigure operation type name {-control_args} | 

FUNCTION I 

adds or deletes selected reconfigurable entities to or from the current configuration. | 

ARGUMENTS | 
operation 

is one of the functions listed below under "List of Operations." 

type I 
is one of the reconfigurable entities listed below under "List of Reconfigurable | 
Entities." | 

name | 
is the name of the item being reconfigured. Examples of names are given under | 
"List of Reconfigurable Entities." i 



2-401 



GB64-00 



reconfigure 



reconfigure 



I CONTROL ARGUMENTS 

I -acid_all_attachments 

I used only after an add operation. This control argument causes all reconfigurable 
I entities which are newly accessible to be added. 

-brief, -bf 

does not print out a list of every item which is added or removed. This is the 
default. 

-delete_all_attachments 

used only after a delete operation. This control argument causes all reconfigurable 
entities which will become inaccessible to be deleted. 

-force, -fc 

causes an FNP to be deleted from the current configuration even if there are 
users connected to the FNP. The FNP is deleted and the users are disconnected. 
(If the -force control argument is not specified when trying to delete an FNP 
with users connected, an error message is produced and the FNP is not deleted.) 

-long, -Ig 

prints out a list of every item which is added or removed. 
LIST OF OPERATIONS 
add 

the specified item is to be added to the current configuration. It will thus 
become available for use. 

delete, dl 

the specified item is to be deleted from the current configuration. It will thus 
become unavailable for use. 

LIST OF RECONFIGURABLE ENTITIES 

channel, chan, chnl 

a logical channel. A channel's name is the name by which lOI knows it (e.g., a9, 
b23). 

cpu 

a Central Processing Unit. A processor's name is its tag as it appears on a cpu 
card in the config deck (e.g., a, b). Only processors that are defined in the 
configuration deck can be added. You must set all of the switches correctly and 
initiaUze the processor before you issue this command. 

device, dv, prph 

a peripheral device. A device's name is the name by which RCP knows it (e.g., 
tapa_03, dskb_13, fnpc, opca). 



2-402 



GB64-00 



reconfigure 



reconfigure 



iom 

an Input/Output Multiplexer. An lOM's name is its tag as it appears on an iom 
card in the config deck (e.g., a, b). 

link_adapter, la 

a link adapter or physical channel. This is a shorthand way of specifying a 
collection of logical channels. A link adaptor's name is the name of its lowest 
numbered channel (e.g.. b28). 

mpc 

a Microporgrammed Peripheral Controller. This is a shorthand way of specifying 
a collection of link adapters (and thus, a collection of logical channels). An 
MFCs name is its name as it appears on an mpc card in the config deck (e.g., 
mspa, mtpb). 

page 

a page of memory. A page's name is its number. Pages are numbered starting at 
0. Numbers may be given in any form acceptable to the cv_integer_string_ 
function. A range of pages may be specified by an expression of the form 
<low>:<high>. Pages to be added must reside within system controllers already in 
the Multics configuration. Pages to be removed must reside within a single system 
controller. 

mem, scu 

a System Control Unit An SCU*s name is its tag as it appears on a mem card 
in the config deck (e.g., a, b). Only system controllers that are defined in the 
configuration deck can be added. You must set all of the switches on the system 
controller correctly before you issue this command. 

ACCESS REQUIRED 

Use of the reconfigure command requires re access to the hphcs_jate. 
NOTES 

When you add an SCU, all of its pages are also added. However, when you delete all 
of an SCU's pages, the SCU itself is not deleted. 

For more details on the dynamic reconfiguration, see the Multics System Maintenance 
Procedures manual. Order No. AM81, and the Operator's Guide to Multics, Order 
No. GB61. 
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C" V AhADI CO 

The examples below assume the following config deck fragment 

iom b 1 iom off 

mpc mspd 607. b 28. 4 

prph dskd b 28. 4 0 I6. 501. I6 <dskd_17 - dskd_32 are 501s> 

mem b 2048. on <conta1ns pages 0 - 20kl> 

mem a 102^*. on <con tains pages 2048 - 307 1> 
cpu c 5 off dps8 70. 32. 

! reconfigure add cpu c 

adds CPU c to the configuration. 

! reconfigure d1 mem a- -del ete_a1 1_attactiments 

deletes SCU a and pages 2048 through 3071 from the configuration. 
! reconfigure add iom b -add__al l_attachments 

adds IOM b to the configuration. MPC mspd is also added, and if any of dskd_17 
through dskd_32 were previously deleted, they are added as well. 



Name: reconstruct_„registiy 
SYNTAX AS A COMMAND 

reconstruct_regi stry regl stry_names {-control_args} 
FUNCTION 

recovers a current copy of RCP resource management registries after a catastrophic 
system failure causing the loss of one or more registries. It assumes that the registry 
to be reconstructed is a consistent earlier copy of the registry desired, and that the 
RCP resource management journal contains a record of all operations performed on 
the registry since the time represented by the earlier copy. 

ARGUMENTS 

registry_names 

are the entrynames of the registries to be reconstructed. You can use the star 
convention. If you give no .rcpr suffix, it is assumed. 
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CONTROL ARGUMENTS 

-pathname path (-pn path) 

to specify the directory in which the registries reside. If this control argument is 
not specified, the registries are sought in >scl>rcp. 

NOTES 

An explanation of the creation and maintenance of checkpointed registry copies can be 
found in the documentation of the copy_registry command. 

The prescribed sequence of operations is to delete the damaged registries; copy the 
desirecJ checkpointed registries into place; and invoke the reconstruct_registry command 
to update the registries. The command locates the RCP Resource Management journal 
relative to the directory in which the registries to be updated reside. 

If an online checkpoint copy of a system registry is not available, a copy of the 
registry may be retrieved from a system backup tape. In this case, the file retrieved 
must be from a time that is more recent than the last time the RCP Resource 
Management journal was reset (see the documentation of the copy_registry command). 

The reconstruction of system registries must only be performed from the Initializer, in 
the "standard" environment, before the answering service is activated. 

ACCESS REQUIRED 

This command requires access to the rcp_sys_ gate. 



Name: record to sector 

SYNTAX AS A COMMAND 
record_to_sector record__no {dev i ce__name} 
SYNTAX AS AN ACT/VE FUNCTION 
[record_to_sector record_no {devi ce_name} ] 
FUNCTION 

converts an octal sector number to a disk sector address. 
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ARGUMENTS 

record_no 

is the octal Multics record number. 

device_name 

is a valid device name (e.g., "m400", "m451"). 



Name: record to vtocx 

SYNTAX AS A COMMAND 

record__to_vtocx pv_name argl ... argN 

record_to__vtocx pv__name -sector sector_argl ... -sector sector__argN 

FUNCTION 

finds any VTOC entries corresponding to a specified record number on a storage 
system volume. 

ARGUMENTS 



pv_name 

is the name of the physical device. 

argi 

is the octal record number. 

sector_argi 

is the octal sector number. 

ACCESS REQUIRED 

You need access to the phcs_ gate. 

NOTES 

Looking for the correct match, this command scans the VTOCEs in ascending order 
for each argument; therefore it uses great amounts of CPU time and requires 
considerable I/O. 



2-406 



GB64-00 



register_mdir 



register_mdir 



Name: register mdir 

SYNTAX AS A COMMAND 

regi ster__mdi r {path} {-control^args} 

FUNCTION 

is used to register an existing master directory in the ring 1 master directory control 
segment (MDCS) for its volume. This may be necessary if the MDCS has become 
damaged or lost. 

ARGUMENTS 

path 

is the name of the master directory to register, or if -all is used, the starting 
node of the hierarchy tree to be scanned for master directories. This argument 
can only be omitted if the -all control argument is specified, in which case it 
defaults to the root. 

CONTROL ARGUMENTS 

-all 

specified that the path given is the starting node to scan for master directories to 
register. All directories including the starting node are checked and registered if 
they are master directories. 

-brief, -bf 

specifies that the names of master directories registered by this command are not 
to be printed. (Applies only when -all is used.) 

ACCESS REQUIRED 

Access to the gate mdc_priv_ is required to use this command. 
NOTES 

This command is only required as part of an error recovery procedure in repairing a 
master directory control segment. Normally, all master directories are registered in the 
MDCS when they are created. 

All master directories registered by this command are charged to the quota account 
Initializer.SysDaemon, which is automatically created if it does not exist 



2-407 



GB64-00 



register_mdir 



register_mdir 



Name: register mdir 

SYNTAX AS A COMMAND 

regi ster__mdi r {path} {-control__args} 

FUNCTION 

is used to register an existing master directory in the ring 1 master directory control 
segment (MDCS) for its volume. This may be necessary if the MDCS has become 
damaged or lost. 

ARGUMENTS 

path 

is the name of the master directory to register, or if -all is used, the starting 
node of the hierarchy tree to be scanned for master directories. This argument 
can only be omitted if the -all control argument is specified, in which case it 
defaults to the root 

CONTROL ARGUMENTS 

-all 

specified that the path given is the starting node to scan for master directories to 
register. All directories including the starting node are checked and registered if 
they are master directories. 

-brief, -bf 

specifies that the names of master directories registered by this command are not 
to be printed. (Applies only when -all is used.) 

ACCESS RE OU I RED 

Access to the gate mdc_priv_ is required to use this command. 
NOTES 

This command is only required as part of an error recovery procedure in repairing a 
master directory control segment. Normally, all master directories are registered in the 
MDCS when they are created. 

All master directories registered by this command are charged to the quota account 
Initializer.SysDaemon, which is automatically created if it does not exist. 
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Name: register resource, rgr 

SYNTAX AS A COMMAND 

rgr type STRl ... STRN {-control_args} 

FUNCTION 

makes a particular resource known to the system. The registration process informs the 
system that the resource is available for users who are authorized to access it 

ARGUMENTS 

type 

is a resource type defined in the RTDT. See "Reserved Names" below for 
additional information. 

STRi 

is the unique identifying name of the particular resource being registered. If STR 
is specified in control argument format (i.e., if it is preceded by a hyphen), then 
it must be preceded by -name or -nm. (The string "scratch" is not permitted.) 

CONTROL ARGUMENTS 

-access_class accr, -acc accr 

sets the initial AIM acce^ class parameters, where accr is an access class range. 
Users at any authorization within the access class range inclusive are allowed to 
read and write to the resource (provided they also meet other access requirements). 

-acs_path path 

specifies the pathname of the access control segment (ACS) for this resource. The 
ACS is not created by this command, but must be created by the administrator, 
and the desired access control list set (see "Notes" below). If this control 
argument is not given, the accounting owner of the resource is given rew access 
by default. If path is a null string, the existing ACS, if any, is disassociated 
from the resource. 

-alloc STR 

sets the allocation state of the resource to free or allocated, where STR must be 
either the string on or the string off. If this control argument is not given, the 
allocation state is free. (The allocation state flag is a convenience to the user and 
is largely ignored by resource management.) on sets the allocation state to 
allocated off sets the allocation state to free 

-attributes STR, -attr STR 

specifies the initial values for the attributes of this resource. If this control 
argument is not given, the default attributes defined in the RTDT for this 
resource type are used (see "Naming Rules for Attributes" below). 
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-comment STR, -com STR 

specifies the initial value of the comment string for this resource. 

-location STR, -loc STR 

specifies a descriptive location for the resource, to aid the operator in locating it 
when it is stored in a special place (e.g., a vault, a different room, etc.). 

-lock STR 

locks or unlocks the resource, preventing or allow^ing use of that resource, where 
STR must be either the string on or the string off. If this control argument is 
not specified the lock is off. 

on prevents any use of the resource 
off allows use of the resource 



-owner STR, -ow STR 

specifies that this resource, as part of the registration process, is to be acquired 
on behalf of the user specified by STR. If STR is the string "system", then the 
resource is acquired to the system pool. If STR is of the form Person_id.Project_id 
(where neither Person_id nor Project_id may be a star), then the user specified 
has all the rights of ownership to the resource as if he had acquired it 
personally, except that if -release_lock on is specified, the owner may not release 
(give up ownership of) the resource voluntarily. If this control argument is not 
given, the resource is entered by default into the free pool. 

-potential_attributes STR, -pattr STR 

specifies the potential attributes to be assigned to this resource. If this control 
argument is not given, the default potential attributes defined in the RTDT for 
this resource type are used (see "Naming Rules for Attributes" below). 

-potential_access_class accr, -pace accr 

sets the potential AIM access class parameters, where accr is the access class 
range. Users at any authorization within the access class range inclusive are 
allowed to acquire the resource. If the control argument is not given, the default 
potential access class defined in the RTDT for this resources type is used. See 
"Access Class Ranges" below, for additional information. 
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-releasejock STR, -rll STR 

specifies whether this resource may be released by the owner, or may only be 
released by a privileged proce^. The STR argument must be either the string on 
or the string off. It is primarily useful to implement special arrangements 
between a site and a user whereby the user agrees to pay a fixed amount for the 
privilege of administrative power over a resource for an agreed-upon length of 
time. If this control argument is not specified, the resource may be released by 
the owner (does not require special privilege). 

on resource may only be released by privileged processor 
off resource may be released by owner 



-type subtype_name, -tp subtype_name 

specifies that defaults for this resource are to be taken from the description of 
the resource subtype as defined in the RTDT (see "Application of Defaults" below 
for additional information). 

NOTES 

If multiple resources are specified to the register_resource command and an error 
occurs in the registration of any of these resources, none of the resources specified is 
registered. 

If no -owner is specified, the resource is placed in the free pool. 

The use of the -access_class, -acs_path, -attributes, or -comment control argument 
requires that the -owner control argument be specified. 

ACCESS REQUIRED 

The use of this command requires execute access to the rcp_admin_ gate. 

Certain specifications of AIM access class parameters (e.g., an access class lower than 
the user's current authorization) are rejected unless the user has the AIM rep privilege. 

ACCESS CONTROL 

There are three types of access control on Multics: discretionary access control, which 
is regulated by access control lists (A.CL); nondiscrstionary access control, which is 
regulated by the access isolation mechanism (AIM); and intraprocess access control, 
which is regulated by the ring structure. (For detailed information on types of access, 
see the Multics Programmers' Reference Manual, Order No. AG91.) 
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ACCESS CONTROL SEGMENTS 

An important feature of RCP is its ability to control access to the various resources 
that it manages. It does this through the use of access control segments (ACSs). An 
ACS is a zero length segment whose ACL and ring brackets are used to define the 
discretionary access to a resource. RCP uses an ACS for each resource that it 
controls; however, an ACS can be shared by more than one resource. The name of an 
ACS consists of a name plus the suffix, acs (e.g., tape_01.acs). There are no 
restrictions on ACS names other than the required suffix. The user creates an ACS 
and generates/ manipulates its ACL with the create, set_acl, and delete_acl commands 
and ring brackets with the set_ring_brackets command. 

The pathname of the ACS for a resource is usually specified when it is acquired. The 
specified ACS can later be changed via the set_resource command (see the Multics 
Commands and Active Functions manual. Order No. AG92). If the ACS has not 
been specified or does not exist, access is by default rew for the owner of the 
resource and null for all other users. 

RCP uses the ACS along with other nondiscretionary controls (AIM) to determine the 
RCP effective access to a resource. 

ACCESS CLASS RANGES 

Access class ranges are used by RCP to specify that a process within a range of 
authorizations can use a particular resource. 

An access class range is simply a pair of AIM access classes separated by a colon. 
The first value of the pair is the minimum access class and the second is the 
maximum access class. If only a single access class is specified when an access class 
range is expected, the minimum and maximum access class values are both the same 
(i.e., a range of one value). The second access class of the pair (the maximum) must 
be greater than or equal to the first (the minimum). 

The user should be aware of results which occur when categories are used in an access 
class range. For example, a process with authorization of: 

1 evel 2, category 1 

would not be able to use a resource whose access class range was: 

level 1 ,categoryl ,category2: level 3»categoryl , category2 , category3 
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where levelS is greater than level2, which is greater than level 1. This is due to the 
fact that the authorization of the process is isolated from the minimum of the access 
class range. In order to allow this process access to the resource in question, the 
range would have to exclude caiegory2 or the user would have to have category2 
authorization. In general, to include categories within an access class range, both the 
minimum and maximum must include the categories desired. If combinations of 
categories are desired, the minimum should list only required categories and the 
maximum should include all categories allowed. For example, the access class range: 

level Ucategoryl : level 3. category 1 ,category2,category3 

allows read and write access to any levell, level2, or levelS process with categoryl and 
any combination of category2 and categoryS. 

RCP EFFECTIVE ACCESS 

Viewed separately, each type of access control answers the same question, "What access 
does a particular process have for a particular item?" The access mode granted a 
process to a resource by discretionary access control (the ACL) is known as the raw 
access mode. 

The way RCP determines eff^tive access to a resource for a process differs from the 
regular Multics method of determining effective access as follows. First, the effective 
access to the ACS for the resource is determined as for any segment. If the ACS 
does not exist, the user appears to have read, execute, and write access if he is the 
owner of the resource, or null access if he is not the owner. Then, two further 
checks are made. First, the current authorization of the process is compared to the 
maximum access class of the resource. If write access is not allowed (as defined by 
the write_allowed_ subroutine) then write and execute access are denied and only read 
is allowed. Next, the current authorization of the process is compared to the minimum 
access class of the resource. If read access is not allowed (as defined by the 
read_allowed_ subroutine) then all access is denied. The resulting access is termed the 
RCP effective access to the resource. One final restriction enforced by RCP is that, 
in order to use a device, the RCP effective access must include both read and write 
to that device (a restriction not imposed on volumes). 

For example, the following table illustrates some examples of RCP effective access. In 
the examples below, LI, L2, L3 and L4 represent sensitivity levels and cl, c2, c3, and 
c4 represent categories. (This discussion mostly concerns devices^- volumes should never 
be given a multiclassed access class range.) 
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Table 2-1. RCP Effective Access 



Effective 
Access 
to ACS 



Current 
Process 
Authorization 



Resource 
Access 
Class Range 



RCP 

Effective 
Access 



rew 


LI 


LI :L3 


rew 


re 


LI 


L1:L3 


re 


rew 


LI 


L2:L3 


nul 1 


rew 


L3 


L2:L3 


rew 


rw 


Lit 


L2:L3 


r 


re 


Lit 


L2:L3 


r 


rw 


L2,cl 


Ll:Llf 


r 


rw 


L2,c2 


LI ,cl :Lit,c1 ,c2 


nul 1 


rw 


L2,cl ,c3 


LI ,cl :Lit,cl ,c2 


r 


rw 


L2,c1 


LI ,cl :Lit,cl ,c2 


rw 



A user must have write RCP effective access to the resource named to perform any 
modification on the status of the resource. In addition, the user must have execute 
effective access to the resource named to modify protected attributes. Only the 
accounting owner may modify the ACS path. 

For more information on AIM, access classes, authorizations, and comparisons involving 
access classes and authorizations, see the Multics Programmer's Reference Manual, 
Order No. AG91. 

MANIPULATING RCP EFFECTIVE ACCESS 

Since the access control mechanisms described above operate together to determine the 
RCP effective access of a process, there are actions that the user, as well as an 
administrator, can perform to control this effective access. 

First, the user creates an ACS via the create command. Then, the desired ACL for 
that segment is established using the set_acl command to add desired ACL entries, and 
the delete_acl command to delete entries. (The above three commands are described in 
the Multics Commands and Active Functions manual. Order No. AG92.) To further 
affect the ACS, the user may modify its ring brackets by using the set_ring_brackets 
command (described in the Multics Commands and Active Functions manual. Order 
No. AG92). The system security administrator sets the AIM access class range of the 
resource itself at the time it is registered using the register_resource command, and 
can change it by using the set_resource command. 
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RESERVED NAMES 



RCP uses the information in the RTDT to decide what classes of resources are known 

to the system, how they are to be handled, and what important attributes they possess. 
In the initial implementation, sites may use this flexibility to augment the standard 
complement of attributes for certain resources. For example, a site with tape drives in 
more than one location may register these drives with an additional simple attribute, 
thereby allowing users to request assignment, of a tape drive in the remote location. 
Additionally, the tape reels in the remote location may be tagged with a matching 
attribute, marked in the RTDT as requiring that attribute of its tape drive. 

Although this mechanism is very flexible, the necessity of having certain standard and 
reserved resource type names and attribute names cannot be avoided. Standard 
software (e.g., tape and disk I/O modules) needs to refer to a domain of resources by 
standard names, as well as certain attributes of the resources. Since these strings must 
be the same at all sites, certain resource types and certain resource attributes must be 
contained in all RTMFs. The cv_rtmf command checks for their existence and refuses 
to process an RTMF that lacks them. This list of required resource type names and 
attributes is also found in the include file, rcp_mandatories.incl.pll. 

RCP does not allow the name "scratch" to be used in registering a resource. A 

scratch tape is one of the unmarked tapes in an unreserved pool that is used for 

"scratch" — that is, no information is saved on it from session to session. After every 
use, it is demounted and returned to the system pool. 



RESERVED RESOURCE NAMES 



The following resources are mandatory and must appear in all RTMFs: 

Device: disk_drive 

Device: tape_drive 

Volume: tape_vo] 

Volume: disk vol 
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RESERVED ATTRIBUTE NAMES 

The following attributes are mandatory for the devices named, and must appear in all 

RTMFs: 

For the disk_drive device: 

mode 1=^00 mode1=ii51 model = l8l 

model = 191 mode I =500 mode 1=402 

For the tape_drive device: 

track=9 
den=556 
den=l600 
mode 1=500 
mode 1 =6 1 0 



NAMING RULES FQR ATTRIBUTES 

Attribute provide a description of a volume or device that agists the resource 
management facility in the proper matching of volumes with compatible devices. To 
produce correct combinations, attribute names must comply with the set of rules 
described below. 

Attributes may be grouped or ungrouped. Grouped attributes specify a set of 
properties applicable to a device or volume such that only one attribute of that set 
can be currently active at any given time. For example, a reel of tape may have 
potential attributes that allow it to be recorded at densities of 556, 800, or 1600; 
however, at any given time, the data on it is in only one of those densities. Grouped 
attributes have names of the form: 

<i dent i f I er>=<va 1 ue> 

For example, the attributes mentioned above are named "den=556", "den=800", and 
"den=1600". This notation allows RCP to recognize that any request to make one of 
these attributes the current attribute of a device or volume also implies that all other 
attributes in that grouping must be made inactive. 

When adding or changing an attribute in a string of attributes, all attributes in the 
string must be respecified or else existing attributes are nullified by the change. Also, 
any attribute string must contain a value for each grouped attribute. For example, if 
the attribute domain includes "track=..., model=..., and den=...," the device you are 
setting the attributes for (or registering) must contain values for each grouped 
attribute. 

Ungrouped attributes have simple nam-es, such as "trainok" (to specify that this device 
accepts a removable print train) or "building_12" (to specify that this device or 
volume is located in building 12). 



track=7 
den=200 
den=800 
mode 1 =400 
mode 1=600 
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APPLICATION OF DEFAULTS 

When the system administrator registers a resource, that resource may be registered 
using the defaults for the registration parameters that are specified in the RTDT. 
Alternately, he may explicitly specify parameters for which defaults may also be 
specified in the table, such as attributes and AIM classes. If any such parameter is 
explicitly specified, the corresponding default for that parameter is overridden. 

When the resource is registered, any default parameters defined for that resource type 
are applied in the absence of a corresponding explicitly specified parameter. 

If the resource is registered with the "-type <subtype_name>" control argument, any 
default parameter defined for the special class named <subtype_name> is applied in 
the absence of a corresponding explicitly specified parameter. In the case of duplicate 
resource type and special class parameters, the special class default parameters override 
the general resource type parameters. In addition, any default parameters specified for 
that resource other than those defaults in the special class are applied. 

If no special classes of a resource are defined, and the defaults for the resource are 
not all present, it is always necessary for the missing parameters to be explicitly 
specified for every registration request for a resource of this type. If special classes 
of a resource are defined, then defaults within the definition of special classes can be 
used either to replace corresponding defaults specified for the resource in general, or 
to supplement for missing defaults that are not specified for the resource in general. 
In the latter case, the system administrator cannot perform a simple default 
registration of the resource, but must either specify the missing items explicitly in the 
com.m.and line, or use the "-type <subtype_name>" control argument to take advantage 
of the additional defaults provided in a special class. 



Name: reload 

SYNTAX AS A COMMAND 
reload {-control_args} 
FUNCTION 

reloads the entire storage system from a hierarchy dump tape. It deletes segments and 
directories from the hierarchy that were not present when the hierarchy dump tape 
was made, and replaces existing segments and directories with their counterparts from 
the tape. However, to avoid destroying useful information, it does not delete 
directories, and it does not replace segments and directories in the hierarchy that were 
modified after the time at which they were dumped to tape. The reload command 
calls the backup_load command to do the actual reloading. 
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The reload command places its map in the directory >reload_dir (to which the process 
must have sma access), and automatically dprints it. Quota on the reloaded directories 
is force-set to that specified on the hierarchy dump tape. 

The reload command is one of the commands used for hierarchy reloading and 
retrieving of storage system segments and directories. The other commands are: 

backup_1oad 

reload (i ni t i al i zer command)^ 
rel oad_system_release 
retr i eve 

Do not confuse this reload command, which is a Multics command, with the reload 
initializer command. 

You should note that argument processing for all of the hierarchy backup commands 

is performed by a common argument processing procedure. The values of all 
arguments are remembered in static storage and remain in effect for the life of the 
process, unless changed by arguments given in subsequent invocations of backup 
commands. It should also be noted that the dumping commands and the reloading/ retrieving 
commands are all part of the same hierarchy backup system, and argument values set 
by the dumping commands remain in effect for the reloading/retrieving commands and 
vice versa, unless overridden. However, dumping and reloading cannot be done in the 
same process; use the new_proc command between dumping and reloading. See "Notes 
on Default Arguments" below. 

CONTROL ARGUMENTS 

-all 

causes segments to be retrieved from the tape regardless of their date/ time 
dumped. This control argument overrides a previously given DATE argument This 
is the default 

-brief _map, -bfmap 

creates a map file that lists the processed entires. 

-debug 

disables those hphcs_ calls that set quotas and transparency switches. 

-destination STR, -ds STR 

specifies a destination for printing maps and error file. The default is 
"incremental" for maps and "error file" for error files. 

-dprint, -dp 

causes the reload command to dprint maps and error files. This is the default. 
-error_of 

writes error messages into a file rather than printing them. The name of the 
error file is printed when the first error is encountered. This is the default 
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-error_on 

writes error messages on the user's terminal, 
-first 

prevents searching a tape for additional copies of a requested segment or subtree 
after the first copy has been retrieved. 

-header STR, -he STR 

specifies a heading for printing maps and error files. 

-last 

indicates that the last copy of a given segment or subtree on a tape or set of 
tapes is to be retrieved. This is the default. 

-map 

writes a list of the segments and directories processed into a file. This is the 
default. 

-nodebug 

enables hphcs_ calls to set quotas and the transparency switches. This is the 
default. 

-nodprint, -no_deprint, -ndp 

causes the reload command not to dprint maps and error files. The default is 
-dprint. 

-nomap 

inhibits listing of the names of processed segments and directories. This control 
argument and the -noreload control argument are incompatible when used with the 
reload command; only one or the other can be used. 

-noprimary, -npri 

uses each pathname as given. The default is -primary. 

-noqcheck 

causes the hierarchy reload to be done with quota checking suspended. Access to 
hphcs_ is required. This is the default. 

-noquota 

inhibits resetting of quotas. See -quota. This is the default. 

■^noreload 

inhibits actual hierarchy reloading of segments into the hierarchy. This control 
argument can be used with -map to create a table of contents of the tape. The 
-noreload control argument also causes the names that would have been reloaded 
to be put into the map. This control argument and the -nomap control argument 
are incompatible when used with the reload command; only one or the other can 
be used. 
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-nosetlvid 

inhibits the setting of the logical volume identifiers for each directory to be 
reloaded. 

-notrim 

inhibits deletion of entries in a directory. Entries can only be added or modified, 
-operator STR 

indicates that STR is the user's name or initials (up to 16 characters in length), 
-primary, -pri 

replaces all directory names in each pathname with the primary names. This is 
the default. 

-pvname STR 

indicates that segments and directories may only be reloaded onto the physical 
volume specified by STR. 

-qcheck 

causes quota restrictions to be enforced during the reload, 
-queue N, -q N 

specifies a queue number for any maps and error files that are dprinted. The 
default is queue 1. 

-quota 

causes the quotas on directories being reloaded to be set to the values they had 
when the directories were dumped. Access to hphcs_ is required. This is the 
default. 

-reload 

enables actual reloading of segments into the hierarchy. This is the default 

-request_type STR, -rqt STR 

specifies an output request type for printing maps and error files. Available 
request types can be listed by using the print_request_types command (described in 
the Multics Commands and Active Functions manual. Order No. AG92 ). The 
default is "printer". 

-setlvid 

enables setting of the logical volume identifier for reloaded entries inferior to 
each directory reloaded. This is the default 

-trim 

enables deletion of all entries in a directory not found in the copy of that 
directory being reloaded. This causes entries deleted from an earlier version of 
the directory to be deleted when a later version is reloaded. This is the default 
It has effect only in the case of a directory that is both on the tape and in the 
hierarchy. 
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DATE 

an argument beginning with a character other than or ">" is assumed to be a 
date in a format acceptable to the convert_date_to_binary_ subroutine. If it can 
be converted successfully, then the hierarchy retriever only retrieves segments and 
directories dumped at or after the given date/ time. 

NOTES ON DEFAULT ARGUMENTS 

The values of arguments given to any of the hierarchy backup commands are 
remembered in static storage and remain in effect for the life of the process, unless 
explicitly changed during the invocation of a subsequent backup command. 

The following defaults are in effect for the reloader and retriever before any backup 
conraiands are given; they are not, however, reset to these values at the start of each 
backup command, except as noted below. 

-all 

-error_of 
-map 

-nodebug 

-nohold 

-noquota 

-primary 

-rel cad 

-set Ivid 

-trim 

The following defaults are set automatically at the time the respective commands are 
executed: 

reload (initializer command), reload (Multics command), 
re 1 oad_sys tem__r e 1 ease : 
-quota 
-tr im 

retr i eve: 

-al 1 

-noquota 
-notr im 

All of the above commands: 
-map 
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Name: remove registry 

SYNTAX AS A COMMAND 
remove_regi stry paths 
FUNCTION 

remove RCP Resource Management registries from service. This command should only 
be used in exceptional circumstances. (See "Notes" below.) 

ARGUMENTS 

path 

is the pathname of a registry to be removed from service. The star convention is 
accepted. If the suffix rcpr is not given, it is assumed. 

NOTES 

When a registry is removed, its suffix is changed from rcpr to old. 

The activity of removing registries is normally reserved to the Initializer process, 

which will automatically remove a registry when a new RTDT is installed that no 

longer contains an entry for the resource type associated with that registry. In general, 

manual removal of registries is only necessary in the process of recovery from a 

catastrophic system failure and reload, where the existing registries and the existing 
RTDT may be out of agreement. Manual removal of registries at other times can 
result in unrecoverable errors by RCP Resource Management. 

ACCESS REQUIRED 

This command requires access to the rcp_sys_ gate. 



Name: remove user 

SYNTAX AS A COMMAND 
remove__user user_name 
FUNCTION 

is used to delete information about a user from both the FNT and the URF. 

ARGUMENTS 

user_name 

(in the form Person_id) is the name of the user to be deleted. 
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Name: reset cdt meters 

SYNTAX AS A COMMAND 
reset_cdt__meters {path} 
FUNCTION 

is invoked by biller.ec at the end of a billing period to reset per-system and 
per-channel usage counters kept in the CDT. 

ARGUMENTS 

path 

is the pathname of the CDT. If path is not specified, the segment >scl>cdt is 
reset 



Name: reset disk meters 

SYNTAX AS A COMMAND 

reset__dl sk_meters {path} {-control__arg} 

FUNCTION 

subtracts the time-page-product (tpp) for each directory in the Multics hierarchy listed 
in disk_stat from the tpp integrator of the directory itself. This operation is done 
once each month after users have been billed for disk usage. Privileged entry points 
in the hphcs_ gate are used to do the work. A comment is printed if the branch 
does not exist or a negative tpp would result, but the program continues. 

ARGUMENTS 

path 

is the pathname of the disk_stat segment containing the usage values to be 
subtracted from the tpp integrators. The default is the segment disk_stat in the 
working directory. 

CONTROL ARGUMENTS 

-brief, -bf 

specifies that the user is not to be informed when it is necessary to force access 
to a directory to reset its tpp. 



2-423 



GB64-00 



reset_disk_meters reset_soos 
NOTES 

This command forces access to directories, if necessary, and removes the access when 
finished. It reports when it must do this, unless the -brief control argument is given, 
and it always reports if unable to force access. 

After resetting all of the tpps, it zeros the per-project disk usage figures in the 
segment projfile, in the working directory. (This segment is an implicit input to the 
command.) 

If the system crashes while this command is running, the command can be restarted 
from the beginning. 



Name: reset soos 

SYNTAX AS A COMMAND 
reset_soos path 

FUNCTION 

resets the security-out-of -service switch for the specified directory after verifying that 
it is consistent with respect to AIM access controls. 

The reset_soos command is needed only if the site is using the AIM access controls. 

ARGUMENTS 

path 

is the pathname of the directory that is to be put back into service. 
ACCESS REQUIRED 

The user must have access to the system_privilege_gate to use this command. 
NOTES 

This command fails and prints an error message if the directory: 

1. is upgraded without terminal quota; 

2. contains segments with an access class unequal to the containing directory: 

3. contains directories with an access class that is not greater than or equal to the 
containing directory; or 

4. contains inconsistent upgraded directories or ring 1 system segments. 
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The star convention is not accepted by this command. Only one pathname argument is 
accepted. 

LIST OF COMMANDS 

The following commands may be used to correct inconsistencies: 

reel ass i f y__seg 
reel ass i f y_d i r 
red ass i f y_sys_seg 
pr i v_inove__quota 



Name: reset usage 

SYNTAX AS A COMMAND 

reset_usage sat_path pdt_dir admin_sat admin_pdt 
FUNCTION 

subtracts the resource usage in each PDT located in an administrative directory from 
the resource usage information in the system copy of each PDT. This procedure 
modifies only the system copy of the PDTs. 

ARGUMENTS 

admin_pdt 

is the pathname of the directory in which administrative copies of the PDTs 
reside. 

admin_sat 

is the pathname of an administrative copy of the SAT. 
pdt_dir 

is the pathname of the directory containing the system copies of the PDTs. 
sat_path 

is the pathname of the system copy of the SAT. 
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NOTES 

This command is used by biller.ec. Projects are billed for the usage recorded in the 
administrative copies of the PDTs. (These copies are created by the crank, called by 
master.ec, from the system copies of the PDTs.) Meanwhile, logged in users are 
accruing additional usage charges, recorded in the system copies of the PDTs. 
Execution of this command subtracts the charges that have just b€«n billed, leaving in 
the system PDTs only the most recently accrued charges that have not yet been billed. 

If the system crashes while this command is running, the command can be restarted 
from the beginning. 



Name: reset use__totals 

SYNTAX AS A COMMAND 
reset_use_total s use_totals control 
FUNCTION 

clears all totals in a month-to-dale statistics data base at the end of a billing period 
and reloads the list of reporting categories. 

ARGUMENTS 

use_totals 

is the pathname of the statistical data base, 
control 

is an ASCII file that classifies projects into reporting categories. 
NOTES 

Each line in the control file is of the form: 
Project__id, reporting category 

All projects in the same reporting category are classified together in the data base by 
the usage_total program. Lines beginning with are ignored. 

The last control line in the file must be of the form: 

other, category title 

to provide for the classification of all other projects. Up to 3258 individual projects 
(in addition to the "other" control line) and 300 category titles may be specified. 
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This command is executed by biller.ec with the arguments: 
today .use__total s dai ly_report. control 

after a copy of the use_totals segment (containing statistics for the month just ending) 
has been saved for historical purposes. This command initializes the today. use_totals 
segment to begin collecting statistics for the next month. This is the only time during 
the month when the classification of projects into reporting categories may be changed. 
The pathname of the control segment, describing the classification, must be given, even 
if the classification is not changing. 

If multiple rate structures are defined at the site, it is recommended that a separate 
category (or group of categories) be used for the projects in each rate structure (i.e., 
that projects of different rate structures not be placed in the same category). The rate 
structure of the first project in each category (in the control file) is used for 
computing usage statistics for all projects in that category. 

If the use_totals segment does not exist, it is created. This segment is updated by the 
system_total and usage_total commands and is input to the system_daily_report and 
system_monthly_report commands. 



Name: response meters 

SYNTAX AS A COMMAND 
response__meters {-control_args} 
FUNCTION 

displays statistics on interactive response time. 

CONTROL ARGUMENTS 

-report_reset, -rr 

generates a report and then performs the reset operation. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 

the last call with --reset specified. If -reset has never been given in the process, 
it is equivalent to having been specified at system initialization time. 

-total, -totals, -tt 

prints summary information for all work classes. 

-work_class N, -wc N 

prints information only for work class number N. 
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ACCESS REQUIRED 

This command requires access to phcs_ or melering_gate_. 
NOTES 

If neither -reset nor -report_reset is specified, response_meters prints a report 

The control arguments -total and -work_class cannot be used together. If either of 
these is used, the remaining control arguments must be such that response_meters 
prints a report. 

The fundamental concept needed to understand the output produced by the response_meters 
command is that of a terminal interaction. A terminal interaction is essentially an 
atomic unit of work by a Multics user at a remote terminal. A terminal interaction is 
triggered by a set of characters keyed by a user at a terminal, which are passed into 
the user ring as a unit. The activity between the receipt of the set of characters at 
the Multics mainframe and the next request by user-ring software for more input is a 
terminal interaction. For a typical user, a terminal interaction corresponds to a line of 
input. Some user-ring software, however, receives input as sets of characters rather 
than as lines (the Emacs editor is an example of such software). For software of this 
sort, a terminal interaction corresponds to the set of characters handed out by ring 0 
TTY software at one time. If, in processing a set of characters keyed by a user at a 
terminal, the user -ring software blocks itself on anything other than terminal input, 
that activity is not considered a terminal interaction. For example, any command that 
results in tape I/O is not considered a terminal interaction. 

The output of response_meters is summarized by work class. Any work class for 
which no interactions were measured is not displayed. The following are brief 
descriptions of the variables printed out by response_meters for each work class and 
for the system: 

WC 

is the work class number. Work class "All" represents statistics for the entire 
system. 

# Thinks 

is the number of times a process in the work class blocked itself awaiting 
terminal input. The term "Think" is used because the delay represented here 
corresponds to what is commonly called "Think Time" in models of interactive 
computer systems. This term is derived from the assumption that during this time 
the interactive user is cogitating about the response just received and is 
formulating an appropriate next input. 

Avg 1 mnKS 

is the average time in seconds for all blocks awaiting terminal input. This is the 
average external delay between interactions to the same process in the work class. 
This external delay includes communications processing time (in the FNP), 
communications line delay, and user idle (or "Think") time. 
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# Queues 

is the number of times a process in the work class was queued for eligibility 

following receipt of terminal input. It may be less than the number of 

interactions because of type-ahead. That is, by keying input sufficiently rapidly, a 

user may cause several interactions to be processed during the same eligibility 
period. It may be larger than the number of Thinks because of perturbations 
associated with process initiation. 

Avg Queues 

is the average eligibility queue time (in seconds) following the receipt of terminal 
input. This is the average clock time between the receipt of the terminal input at 
the Multics mainframe and the awarding of eligibility to the target process by 
traffic control. The average queue time corresponds to what is called "response 
time" in the output of traffic_control_meters. 

Load Control Group 

is the set of Load Control Groups corresponding to the work class. Read access 
to the Answer Table and to the Master Group Table (MGT) is required for this 
information to be displayed. If the requesting process does not have this access, 
then this field is left blank. 

Response times by VCPU Range 

Up to four detail lines and one summary line are printed, with each line 
corresponding to a set of interactions. Each interaction measured is categorized by 
the amount of virtual CPU time consumed by the interaction. Based on the 
virtual CPU time for the interaction, the interaction is recorded against one of 
four "buckets." Each of the detail lines represents all terminal interactions for 
processes in the work class that fell into the corresponding "bucket." A bucket is 
simply a range of virtual times. Intuitively, the first bucket represents trivial 
interactions, the last bucket represents exceptionally long interactions, and the 
remaining two buckets lie between these extremes. If there were no interactions 
recorded against a bucket, the detail line corresponding to that bucket is not 
printed. The summary line contains information on all terminal interactions for 
processes in the work class. 

VCPU Range 
From 
To 

is the range of virtual CPU times for interactions presented on that line, in 
seconds. "From" is the beginning of the range, and "To" is the end of the range. 

The summary line is identified by " " in both the "From" and the "To" 

fields. 

# Int 

is the number of interactions in the bucket for the line. That is, this is the 
number of interactions whose virtual CPU time fell between the values of "From" 
and "To." 

Avg VCPU 

is the average virtual CPU time per interaction for the bucket. 
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Avg RT 

is the average response lime per interaction for the bucket. It is the average 
clock time required to process an interaction, including any eligibility queue time. 

Resp Fact 

is the response factor. This is defined as the ratio of the average response time 
per interaction to the average virtual CPU time per interaction. Intuitively, this 
ratio represents an "extension factor" for virtual CPU time. That is, it is a factor 
expressing the average amount of clock time required to process an interaction 
with a given virtual CPU time. This nimiber can be used as a "quick" indicator 
of work class or system performance. 



In addition to the per-work class data described above, the following summary 
information is displayed: 

calls to meter_response_time 

is the number of subroutine calls to the ring 0 routine that collects the raw 
response time data. 

invalid transitions 

is the number of invalid calls to this routine; meter_response_time implements a 
finite-state automaton that models a terminal user's interaction with the Multics 
system. The number of invalid transitions is the number of events that did not 
fit into this models. Typically, invalid transitions result from perturbations 
associated with process initiation. 

Overhead 

is the CPU time consumed by the measurement routine, expressed as a percentage 
of total system CPU time, and as the average CPU time in milliseconds per call 
to this routine. 



EXAMPLES 



The following is an example of the information printed when the response_meters 
command is invoked with no control argument (See Appendix A for a representation 
of the configuration deck used to create the system from which the metering saple 
was taken.) 



Total metering time 0:15:30 
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Overhead = 0.09% ( 0 .01+6 ms . /ca 1 1 ) 



Name: restore pdt access 

SYNTAX AS A COMMAND 

res tore_pdt_access {Project_id} 

FUNCT/ON 

can be invoked after a crash to fix the ACLs on some system accounting data bases. 
The program ensures that the system and project administrators have the necessary 
access on the PDT and on the >scl>proj_admin_seg segment and the >scl>update 
directory. 

ARGUMENTS 

Project_id 

is the name of the project to be checked. If Project_id is supplied, only one 
project is repaired. Otherwise, all projects are checked. 
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Name: retrieve 

SYNTAX AS A COMMAND 
retrieve path {-contro]_args} 
FUNCTION 

retrieves specified storage system segments, directories and subtrees. It does this by | 
copying them from a hierarchy dump tape into the hierarchy, possibly into different ] 
places in the hierarchy than those from which they were originally dumped. The j 
retireve command calls the backup_load command to do the actual retrieving. | 

The retrieve command requires a retrieval control file, containing the pathnames of the | 

objects to be retrieved. It calls backup_load once for each line in the control file. | 

See "Notes on Format of a Retrieval Control File" below. Cross retrievals are allowed; | 

i.e., objects can be retrieved into different places in the hierarchy than those specified | 

on the dump tape. The retrieve command places its maps in the working directory | 

and doesn't automatically dprint them. Quota on the retrieved directories is not j 

force-set. | 

The retrieve command is one of the commands used for hierarchy reloading and i 
retrieving of storage system segments and directories. The other commands are: j 

backup_load i 
reload (initializer command) i 
reload (Multics command) i 
re 1 oad_sys tem_re 1 ease j 

You should note that argument processing for all of the hierarchy backup commands 
is performed by a common argument processing procedure. The values of all 
arguments are remembered in static storage and remain in effect for the life of the 
process, unless changed by arguments given in subsequent invocations of backup 
commands. It should also be noted that the dumping commands and the reloading/ retrieving 
commands are all pan of the same hierarchy backup system, and argument values set 
by the dumping commands remain in effect for the reloading/ retrieving commands and 
vice versa, unless overridden. However, dumping and reloading cannot be done in the 
same process; use the new_proc command between dumping and reloading. See "Notes 
on Default Arguments" below. 

ARGUMENTS 

path 

is the absolute pathname of a retrieval control file (see "Notes on Format of a 
Retrieval Control File" below). This argument is required. It can be given 
anywhere on the command line. 
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CONTROL ARGUMENTS 
-all 

causes segments to be retrieved from the tape regardless of their date/ time 
dumped. This is the default. This control argument overrides a previously given 
DATE argument. 

-brief _map, -bfmap 

creates a map file that lists the processed entries. 

-control path 

indicates that path is a hierarchy retrieval control file pathname. See "Notes on 
Format of a Retrieval Control File" below. 

-debug 

disables those hphcs_ calls that set quotas and transparency switches. 

-destination STR, -ds STR 

specifies a destination for printing maps and error file. The default is 
"incremental" for maps and "error file" for error, files. 

-error_of 

writes error merges into a file rather than printing them. The name of the 
error file is printed when the first error is encountered. This is the default. 

-error_on 

writes error messages on the user's terminal, 
-first 

prevents searching a tape for additional copies of a requested segment or subtree 
after the first copy has been retrieved. 

-header STR, -he STR 

specifies a heading for printing maps and error files. 

-last 

indicates that the last copy of a given segment or subtree on a tape or set of 
tapes is to be retrieved. This is the default. 

-map 

writes a list of the segments and directories processed into a file. This is the 
default. 

-nodebug 

enables hphcs_ calls to set quotas and the transparency switches. This is the 
default. 

-nomap 

inhibits listing of the names of processed segments and directories. 
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-noprimary, -npri 

uses each pathname as given. The default is -primary. 

-noqcheck 

causes the hierarchy reload to be done with quota checking suspended. Access to 
hphcs_ is required. This is the default. 

-noquota 

inhibits resetting of quotas. See -quota. This is the default 
-noreload 

inhibits actual hierarchy reloading of segments into the hierarchy. This control 
argument can be used with -map to create a table of contents of the tape. The 
-noreload control argument also causes the names that would have been reloaded 
to be put into the map. 

-nosetlvid 

inhibits the setting of the logical volume identifiers for each directory to be 
reloaded. 

-notrim 

inhibits deletion of entries in a directory. Entries can only be added or modified. 
This is the default 

-operator STR 

indicates that STR is the user's name or initials (up to 16 characters in length), 
-primary, -pri 

replaces all directory names in each pathname with the primary names. This is 
the default 

-pvname STR 

indicates that segments and directories can only be retrieved onto the physical 
volume specified by STR. 

-qcheck 

causes quota restrictions to be enforced during the reload, 
-quota 

causes the quotas on directories being reloaded to be set to the values they had 
when the dir^tories were dumped. A^ecess to hphcs_ is required. 

-reload 

enables actual reloading of segments into the hierarchy. This is the default 

-request^type STR, -rqt STR 

specifies an output request type for printing maps and error files. Available 
request typ6s can be listed by using the print_request_ types command (described in 
the Multics Commands and Active Functions manual. Order No. AG92 ). The 
default is "printer". 
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-setlvid 

enables setting of the logical volume identifier for reloaded entries inferior to 
each directory reloaded. This is the default. 

-trim 

enables deletion of all entries in a directory not found in the copy of that 
directory being reloaded. This causes entries deleted from an earlier version of 
the directory to be deleted when a later version is reloaded. It has effect only in 
the case of a directory that is both on the tape and in the hierarchy. This is the 
default. 

DATE 

an argument beginning with a character other than or ">" is assumed to be a 
date in a format acceptable to the convert_date_to_binary_ subroutine. If it can 
be converted successfully, then the hierarchy retriever only retrieves segments and 
directories dumped at or after the given date/ time. 

NOTES ON DEFAULT ARGUMENTS 

The values of arguments given to any of the hierarchy backup commands are 
remembered in static storage and remain in effect for the life of the process, unless 
explicitly changed during the invocation of a subsequent backup command. 

The following defaults are in effect for the reloader and retriever before any backup 
commands are given; they are not, however, reset to these values at the start of each 
backup command, except as noted below. 

-al 1 

-error_of 
-map 

-nodebug 

-nohold 

-noquota 

-pr imary 

-reload 

-setlvid 

-tr im 
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The following defaults are set automatically at the time the respective commands are 
executed: 

reload (initializer command), reload (f^ultics command), 
rel oad_system_rel ease: 
-quota 
-tr im 

retr i eve: 
-all 

-noquota 
-notr im 

All of the above commands: 
-map 



NOTES ON FORMAT OF A RETRIEVAL CONTROL FILE 

The hierarchy retrieval is controlled by an ASCII segment containing one line for each 
object to be retrieved. A line can contain a single pathname or two pathnames 
separated by an equal sign. The left-hand side specifies the segment or directory 
sought and the right-hand side, if present, specifies the new name under which that 
entity is to be retrieved. The sought pathname must begin with a > and end with 
either an entryname or the characters >**. If an entryname is specified, a single 
object of that name is retrieved. 

If >** is specified, the entire directory hierarchy, beginning at the point indicated in 
the pathname, is retrieved. In this case, the right_hand pathname, if present, ends in 
the name of the directory under which these entries are to be reloaded. For example: 

>udd>one_d i r>"*=>udd>two_d i r 

If a new name is specified on the right, it can be either a pathname or an 
entryname. If an entryname is given, the single object found is loaded with its former 
pathname and the new entryname. 

If two pathnames are specified, both are checked against the current hierarchy and a 
new pathname consisting only of the primary entryname is created. This new 
pathname, as well as the original, is then used in searching the hierarchy. For 

example, >udd>sd is translated into >user_dir_dir>SysDaemon and both versions are 
sought. Primary names are used unless the -noprimary control argument is in effect 

A hierarchy retrieval control file can contain a maximum of 256 lines. 
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EXAMPLES 

A hierarchy retrieval control file containing the line: 
>udd>Mul tics>** 

searches the tape for directories and segments whose first two pathname components 
are >user_dir_dir>Multics. These items are retrieved as found. 

A hierarchy retrieval control file containing the line: 

>ldd>a>b>c 

searches the tape for the segment >library_dir_dir>a>b>c. This item is retrieved as 
found. 

A hierarchy retrieval control file containing the line: 
>ldd>a>b=c 

search^ the tape for the segment >hbrary_dir_dir>a>b. This item is retrieved under 
the name >idd>a>c, 

A hierarchy retrieval control file containing the line: 
> 1 dd>x>y>*J'«=> 1 dd>2>y 

searches the tape for directories and segments whose first three pathname components 
are >library_dir_dir>x>y. These itMis are retrieved in die subtree >ldd>z>y. 



Name: ring zero dump, rzd 
SYNTAX AS A COMMAND 

rzd segname {offset} {length} {-control__args} 

SYNTAX AS AN ACTIVE FUNCTION 

[rzd segname {offset} {-control_args}] 

FUNCTION 

prints or returns the locations of the specified ring 0 or user ring segment in 
full-word octal format. 
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ARGUMENTS 
segname 

is an octal segment number, the name of a ring 0 segment, or a pathname. To 
specify a segment name that consists entirely of octal digits, precede the name by 
-name. 

offset 

is the (octal) offset of the first word to be dumped. If you omit both offset 
and length, the entire segment is dumped. If you use -ep, omit offset 

length 

is the (octal) number of words to be dumped. If you supply offset and omit 
length, one word is dumped. 

CONTROL ARGUMENTS 

-4bit 

prints or returns a translation of the octal or hexadecimal dump based on the 
Multics unstructured four-bit byte. The translation ignores the first bit of each 
nine-bit byte and uses each of the two groups of four bits remaining to generate 
a digit or a sign. 

-address, -addr 

prints the address (relative to the base of the segment) with the data. (Default) 

-bed 

prints the BCD representation of the words in addition to the octal or 

hexadecimal dump; in the active function, returns BCD. There are no nonprintabie 
BCD characters, so take periods literally. 

-block N, -bk N 

dumps words in blocks of N words separated by a blank line. The offset, if 
being printed, is reset to the initial value at the beginning of each block. 

-character, -ch, -ascii 

prints the ASCII representation of the words in addition to the octal or 
hexadecimal dump; in the active function, returns ASCII. Characters that cannot 
be printed are represented as periods. 

-ebcdicS 

prints the EBCDIC representation of each eight bits in addition to the octal or 

that cannot be printed are represented by periods. If an odd number of words is 
requested for a dump, the last four bits of the last word do not appear in the 
translation. 
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-ebcdic9 

prints the EBCDIC representation of each nine-bit byte in addition to the octal 
or hexadecimal; in the active function, returns nine-bit EBCDIC. Characters that 
cannot be printed are represented by periods. 

^ntry_point name, -ep name 

specifies that the offset of the first word to be dumped is relative to the 
location defined by the externally available symbol "name." You can use this 
control argument only for object segments (created by a compiler or the 
create_data_segment command). If you supply offset, omit -ep. 

-header, -he 

prints a header line containing the pathname (or segment number) of the segment 
being dumped as well as the date or time printed. (Default to print a header 
only if the entire segment is being dumped, i.e., if you specify neither the offset 
nor the length argument) 

-hex8 

prints the dumped words in hexadecimal with eight hexadecimal digits per word, 
rather than 12 octal digits per word. Each pair of hexadecimal digits corresponds 
to the low-order eight bits of each nine-bit byte. 

-hex9 

prints the dumped words in hexadecimal with nine hexadecimal digits per word, 
rather than octal with 12 octal digits per word. 

-long, -Ig 

prints eight words on a line. You can't use -long with -4bit, -bed, -character, 

-ebcdicS, -ebcdic9, or -short (Its use with these control arguments, other than 

-short, results in a line longer than 132 characters.) (Default four) 

-name path, -nm path 

indicates that path is the name of a ring 0 segment or a pathname, even though 
it may look like an octal segment number. 

-no_address, -nad 

does not print the address. 

-no_header, -nhe 

does not printing the header line, even though the entire segment is being 
dumped. 

-no_offset, -nofs 

does not print the offset (Default) 

-offset N, -ofs N 

prints the offset, relative to N words before the start of data being dumped, 
along with the data. If you supply no N, zero is assumed. 
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-rest I 
prints from any given offset (specified by -ofs or the offset argument) to the | 
end of the segment | 

-short, -sh 

compacts lines to fit on a terminal with a short-line length. Single spaces are 
placed between fields, and only the two low-order digits of the address are 
printed, except when the high-order digits change. This shortens output lines to 
less than 80 characters. 

ACCESS REQUIRED 

You need no access to phcs_ gate for those segments accessible through the 
rin&_zero_peek_ subroutine. 

NOTES 

You can give only one of -4bit, -bed, -character, -ebcdicS. or -ebcdic9. 

As an active function, rzd returns only one word of information, which is located at 
offset, with the segment If you supply -4bit -bed, -character, -ebcdic9, -ebcdicS, 
-hex8, or -hex9, the information is returned in the specified format only. All other 
arguments are ignored in the active function. 



Name: salvage dir 
SYNTAX AS A COMMAND 

sa1vage_dir dir_path {output^path} {-control^args} | 
FUNCTION 

verifies and/or rebuilds one directory. You can use it only in ring 4. 

The command "x repair" causes one or more daemons to be logged in to perform an 
online salvage using salvage_dir. Preferably, perform an online salvage this way. 

ARGUMENTS 

dii_path 

is the pathname of the directory being salvaged. 

output_path I 
is the pathname of the segment or multisegment file (MSF) to which the salvager 
messages should be appended. If the segment does not exist, it is created. If you ■ 
don't specify it, output goes to user.output 
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CONTROL ARGUMENTS 
-check_vtoce 

checks VTOC entries for all branches in the directory. These checks update the 
permanent information in the VTOC entry and detect connection failures. 

-compact 

specifies rebuilding of the directory if one or more pages are recovered. 

-delete_coiinection_failure, -dcf 

deletes branches for segments that do not have corresponding VTOC entries. The 
default is not to delete such branches. This control argument updates permanent 
VTOC entry information. This argument makes subsequent volume retrieval of the 
lost data more expensive because both the data and the branch must be recovered. 

-rebuild 

forces rebuild of the directory. 

LIST OF ADDITIONAL CONTROL ARGUMENTS 

The following control arguments are used for software debugging: 

-debug, -db 

prints additional trace information. Because this information includes offsets in 
the original directory, use -dump also. 

-dump path 

specifies that a copy of the directory should be placed in a segment in the 
directory specified by path. The copy is created only when certain error 
conditions are detected during salvage. 

EXAMPLES 

The following command salvages all directories and appends the diagnostic messages to 
the segment salv.messages in >dumps: 

wa1k_subtree "salvage_dir [wd] >dumps>salv_messages" -msf -priv 
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Name: salvage mstb 

SYNTAX AS A COMMAND 
salvage_mstb path {N} 
FUNCTION 

rebuilds an overloaded MSTB, or recovers the contents of a damaged MSTB. | 

ARGUMENTS 

path 

is the pathname of the MSTB to be recovered. 

N 

is the number of entries to make in the new table. The default is three times 
the number of used entries in the old table, making the new MSTB 33% full. 

NOTES 

Never salvage a "live" MSTB. A ^Ivage operation should be performed on a saved j 

copy only. The PNT and the mail table should be salvaged in special session, then j 

moved back in place before the answering service is restarted. | 

The URF can be salvaged whenever it is not in use by any process. 

Entri^ in an MSTB are accused imng a hashiii| algorithm. For most efficient 
operation, it is fasdmiaended that the Pkt be k^pt betw^n 30% and 50% full and the 
URF between 50% and 70% full. 



Name: save history__r^sters 

SYNTAX AS A COMMAND 

save__hi story_regi sters {state} {-control_args} 
FUNCTION 

allows a user to save processor history registers upon each occurrence of a si^alable 
fault in the signalers stack frame. By default, the history registers are not saved, and 
the history register block in the signalers stack frame is set to all zeros. 

ARGUMENTS 

state 

can be either "on" or "off." If state is not specified, it is off. 
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CONTROL ARGUMENTS 
-priv 

specifies manipulation of the per-system state by directing the state and -print 
arguments to operate on the per-system history register save switch, 
wired_hardcore_data$global_hregs. When set, this switch causes all processes to 
save their history registers upon each occurrence of a signalable fault in the 
signalers stack frame. If -priv is not specified, then the state and -print 
arguments operate on pds$save_history_regs, the per-process history register save 
switch of the process executing this command. 

-print, -pr 

displays the current state of the history register save switch if the state argument 

is not specified; if the state argument is specified, the stale of the switch is 

displayed before the new state is applied. 

ACCESS REQUIRED 

When -priv is used, hphcs_ access is required. 



Name: scavenge vol 

SYNTAX AS A COMMAND 

scavenge__vol {pvname} {-control_args} 
I SYNTAX AS AN ACTIVE FUNCTION 
j [scavenge_vol {pvname} {-control_args} ] 

FUNCTION 

invokes the Scavenger to scavenge one or more physical volumes. The Scavenger 
examines and validates VTOCEs, deletes per-process and per-bootload VTOCEs from 
previous bootloads, recovers lost VTOCEs, recovers lost records, and checks for reused 
I addresses (two VTOCES claiming the same record address). See the Multics System 
j Maintenance Procedures manual. Order No. AM81, for a description of scavenging. 

If no control arguments are specified, no default actions are taken. 

j The initializer command "x scav" logs in a daemon to perform a scavenge using the 
scavenge_vol command. 



2-444 



GB64-00 



scavenge_vol 



scavenge_vol 



ARGUMENTS 
pvname 

is the name of the physical volume to be scavenged. It must be part of a 
mounted logical volume. This argument is required unless the -all or -Iv control 
argument is specified. 

CONTROL ARGUMENTS 

-all, -a 

scavenges, in turn, all mounted physical volumes, 
-auto 

controls scavenging of physical volumes when the -Iv or -all control argument is 
specified. When this option is used, those physical volumes with volume 
inconsistencies are scavenged. 

-check 

validates the command control arguments and prints a list of physical volumes 
that would be scavenged as a result of the command line input, but does not 
actually perform the scavenge. 

-debug 

should be used only by systems programmers debugging the Scavenger. It causes 
additional information to be printed on the bootload console during the scavenge. 

—dump 

records the VTOCE image of any VTOCE found inconsistent into the syserr log. 
The image recorded is the VTOCE prior to any correction by the Scavenger. 

-Iv Ivname 

scavenges, in turn, all physical volumes belonging to the logical volume specified 
by Ivname. The logical volume must be mounted. 

-no_optimize, -nopt 

disables optimization of Scavenger processing. This causes the Scavenger to take 
longer, but reduces its effect on other users of the system. With this option, 
VTOCE read -ahead is disabled, and the Scavenger periodically lowers its traffic 
control priority. 

ACCESS REQUIRED 

Access to the hphcs_ gate is required. 

NOTES 

The scavenge of each volume is done entirely in ring 0. Any error messages are 
recorded into the syserr log. It is possible to interrupt a scavenge of a volume with 
the QUIT key, but it cannot be restarted afterwards with the start or program_interrupt 
commands. 
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j When the scavenge_vol command is invoked as an active function, it returns a list of 
physical volumes that would be scavenged, separated by spaces. The -check control 
argument is the default for active function usage, i.e., scavenging is not done. 



Name: so ^command 

SYNTAX AS A COMMAND 

sc_command i ni t i al i zer_command {arguments} 
FUNCTION 

allows initializer commands to be executed from admin mode. 
NOTES 

This command is used in exec^coms such as system_start_up.ec and admin.ec, and in 
some uses of the sefld_admi3l_00fliifland (sac) command. In these cases, the initializer 
process is executing is admia mode (see the admin command earlier in this section) 
and expects normal Multies commands. Any initializer commands to be executed in 
these cases must be executed by using sc_command. 

However, because sc_command is executed from within admin mode (whether typed by 
the user or sent via the sac command), the initializer^command argument cannot be a 
command that re-centers admin mode (for example, the exec ["x"] command). In 
order to accomplish this, the x command can be replaced by "ec admin {arp}". 

I Administrators should avoid using the sac command to send initializer commands that 
I ask questions, because the qu^tions will be asked on the bootload console. Use of the 
answer command solves this problem for Multies commands seat via sac. but the 
I answer command cannot be used to supply answers to initializer commands, since most 
I initializer commands ask tiieir questioii using a different interface from normal Multies 
I commands. 

EXAMPLES 

In admin.ec: sc^command reply prta driver 

From an administrator: sac "sc_command unbump Smith SysAdmin" 
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Name: sector to record 

SYNTAX AS A COMMAND 
sector_to_record record_no {dev i ce_name} 
FUNCTION 

converts an octal sector address to a Multics record number. 

ARGUMENTS 

record_no 

is the octal Multics record number. 

device_name 

is a valid device name (e.g., "m400", "m451"). 



Name: send_admin_^command, sac 

SYNTAX AS A COMMAND 

sac {-contro1_args} command] ine 

FUNCTION 

sends a command line to the initializer process for execution. 

ARGUMENTS 

commandline 

is the command line to be sent to the initializer. To send special characters you 
must enclose them (or the whole command line) in quotes. If the first character 
of the command is a character, the "-string" control argument must be used. 

CONTROL ARGUMENTS 

-address MAIL.ADDRESS 

specifies that mail sent for notifications is to be sent to the mail address 
specified by MAIL_ ADDRESS. In most cases, the MAIL_ADDRESS can be in the 
form Person_id.Project or Person^id. (Type "help mail_addresses.gi" for additional 
information on mail address specification). 

-brief, -bf 

suppresses the printing of informational messages. 
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I -brief _query, -bfqy 

I specifies that a brief query is to be posed before the command is executed, 
-long, -Ig 

prints the messages suppressed by -brief. This is the default. 
I -no_notify_by_message, -nntmsg 

I specifies that the user is to receive no interactive messages concerning the 
j execution of the command, except in the special case that -no_wait is specified 
I and the execution of the command is denied due to lack of access. 

-no_query, -nqy 

specifies that no query is to be posed before sending the command line. This is 
the default. 

I -no_wait, -nwt 

I specifies that the command return to the listener as soon as the commandline has 

I been sent to the initializer. 

I 

I -notify_by_mail, -ntmail 

I specifies that the user is to be sent mail in the following cases: (1) -no_wait is 

j specified, and execution of the command line is denied due to lack of access. (2) 

I the command completes execution. 

I By default, the mail will be sent to the destination specified in the user's mail 

I table entry. If no destination is found there, the full User.Project specification 

I will be used. The default may be overridden with the -address control argument. 

I If the command is executed, the mail will contain all output produced on the 

j error_output, user_outpul, and user_i/o switches during the command execution. 

I -notify_by_message, -ntmsg 

I specifies that the user is to receive a brief notification by interactive message in 

I the following cases: (1) -no_wait is specified, and execution of the command line 

I is denied due to lack of access. (2) The command completes execution. 

If possible, the user's mail table entry will be used to determine the delivery 
address. If not, the full User.Project specification will be used. The -address 
control argument does not apply to interactive messages. 

I -query, -qy, -long_query, -Igqy 

I specifies that the command line is to be displayed on the terminal and that the 

[ user is to be queried before the command line is executed. This control argument 

I is useful for validating the effects of abbrevs and active functions. 

-string 

specifies that the rest of the command line is to be interpreted as the command 
to be executed, whether or not it begins with a 
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-wait WAIT.TYPE, -wt WAIT.TYPE 

specifies that the command must wait for a specified event before returning to 
the hstener. WAIT_TYPE can be one of the following values: 

start 

specifies that the command is to wait for the initializer to acknowledge 
receipt of the command line before returning to the listener. 

finish 

specifies that the command is to wait for the inititalizer to finish execution 
of the command line before returning to the listener. This is the default. 

ACCESS REQUIRED 

RW access to >scl>admin_acs>send_admin_command.acs is required to use this 
command. 



Name: send daemon ^command 

SYNTAX AS A COMMAND 

send_daemon_comniand request {Person_i d . Project_i d} source_id 

{command_l i ne} 

FUNCTION 

allows control over daemon processes from normal user processes. This command is 
used to login/ logout the daemon, send a quit signal to the daemon, or send a reply to 
the daemon. 

ARGUMENTS 

request 

can be one of the following requests, 
login 

login in the specified daemon, 
logout 

logout the specified daemon. 

quit 

send a quit signal to the specified daemon, 
reply 

send a reply to the specified daemon. 
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I Person_id.Project_id 

I is the user_id of the daemon process to be logged in. This argument must be 
I supplied for the login request and is valid for that request only. 

I source_id 

I is the message coordinator source name associated with the daemon (e.g., bk, vine, 
I ut, scav). 

command_line 

is the command line to be submitted to the daemon via the reply request or 
optional login control arguments for the login request. This argument is not valid 
for the logout or quit requests. If the command line contains special characters, 
they must be enclosed in quotes (or the whole command line can be enclosed in 
quotes). 

I ACCESS REQUIRED 

I If the validate_daemon_commands keyword in installation_parms is set "off," rw access 
I to >scl>admin>send_daemon_command.acs is required to use this command. 

I If the validate_daemon_commands keyword in installation_parms is set "on," then the 

j following access is required to use the send_daemon_command. 

I i. The login and logout requests require "e" (control) access on the acs segment 

I associated with the daemon source_id. Additionally, the login request requires that 

I the daemon identified by Person_id.Project_id have "d" (daemon) access to the acs 

I segment associated with the daemon source_id. 

] 2. The quit request requires "q" (quit) access on the acs segment associated with the 

I daemon source_id. 

I 3. The reply request requires "r" (reply) access on the acs segment associated with 

I the daemon source_id). 

j NOTES 

I The send_daemon_command cannot be used within the sac command (use sc_command). 

I EXAMPLES 

I send__daemon_command login rp R,epa i r .SysDaemon -auth system_high 

I send_daemon_command quit rp 

I send_daemon__command reply rp pwd 

I send__daemon_command logout rp 
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Name: send ips 

SYNTAX AS A COMMAND 
send_ips process_id signal__name 
FUNCTION 

sends an IPS signal to a process. It is a command interface to the hphcs_$ips_wakeup 
subroutine entry point 

ARGUMENTS 

process_id 

is a 12-digit octal number specifying the ID of the process that is to receive the 
signal. You can omit leading zeros from proceK_id. 

signal_name 

is name of one of the system-defined IPS signals; it can be up to 32 characters 
long. The signal names must be defined in sys_info_$ips_mask_data. Presently the 
defined signal names are quit, alrm, neti, cput, trm_, sus_, wkp_, pgt_, 
system_shutdown_scheduled_, and dm_shutdown_scheduled_. 

ACCESS REQUIRED 

You need access to the highly privileged hphcs_ gate. 
NOTES 

No error message is given if you supply an undefined IPS signal or a nonexistent 
process. 

The process_id active function is a convenient way of obtaining a process_id, given a 
User_id or channel name. 



Name: send wakeup 

SYNTAX AS A COMMAND 

send_wakeup process_id event_channel {event_message} 
FUNCTION 

sends an IPC wakeup to a process. It is a command interface to the hcs_$ wakeup 
subroutine entry point. 
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ARGUMENTS 
process_id 

is a 12-digit octal number specifying the ID of the process that is to receive the 
wakeup. Leading zeros can be omitted. 

event_channel 

is a 24-digit octal number specifying the event channel over which the wakeup is 
to be sent. Leading zeros can be omitted. 

event_message 

is an optional 72-bit event message, given as either a 24-digit octal number or an 
eight-character ASCII string. The default is all zero bits. Leading zeros or 
trailing blanks can be omitted. The event message is assumed to be in octal form 
if it contains only octal digits. 

NOTES 

Nonexistent processes and event channels of invalid format are diagnosed; however, 
validly formed but nonexistent event channels are not diagnosed. 

The process_id active function is a convenient way of obtaining a process id, given a 
User_id or channel name. 



Name: set dir quota 

SYNTAX AS A COMMAND 

set_di r__quota pathl quota! ... pathN quotaN 
FUNCT/ON 

places an arbitrary secondary storage quota for directories on a specified directory. 
Incorrect use of this command can make portions of the hierarchy unusable because of 
quota violations. 

ARGUMENTS 

pathi 

is the name of the directory on which the directory quota is to be placed. The 
active function -wd can be used to specify the working directory. 

quotai 

is the directory quota in 1024 word pages. 
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ACCESS REQUIRED 

The user must have access to the highly privileged gate hphcs_ to use this command. 
NOTES 

No permission in the directory is required to use this command. It is not necessary 
that the new directory quota be greater than the current number of pages being used 
by directories in this directory. This command attempt to set a terminal directory 
quota even if it is set to zero. This command does not cause the inferior counts of 
the superior directory to be updated. 



Name: set flagbox 

SYNTAX AS A COMMAND 
set__flagbox f lagbox_variable 
FUNCTION 

sets the value of a specified flag in the BCE/Multics communication area. 

ARGUMENTS 

flagbox_variable 

is one of the valid flagbox variables listed below: 

bce_command command 

is a command to be invoked by BCE when it reaches a command level. This 
command is set so that if the system should crash, this command is 
automatically executed. Refer to the Multics System Maintenance Procedures 
manual. Order No. AM81 for m.ore details. 

keyword value 

may be either a number from 1 to 36 or the corresponding name of one of 
the flagbox flags as given below. The names of the flagbox flags are: 
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auto_reboot 
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boot i ng 
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bi t3 
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rebooted 
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bits 
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bits 


10 


bitlO 
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value 

is either true or false. 
ACCESS REQUIRED 

Privileged access to hphcs_ is required to use this command. 



Name: set log history dir 

SYNTAX AS A COMMAND 

set_log_history__dir log__seg_path history__dir_path 
FUNCTION 

changes the pathname of older log segments recorded in a log segment's header. 
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ARGUMENTS 
lo&_seg_path 

specifies the log segment history.dir pathname that is to be changed. 

history_dir_path 

specifies the new history.dir \o% segment pathname. If this pathname is not the 
name of an existing directory, you are queried whether or not this change is to 
be made. 

ACCESS REQUIRED 

You need write access to the selected log segment 



Name: set_„mc_message_liiiiits 
SYNTAX AS A COMMAND 
set_mc_message_l imits {-control_args} 
FUNCTION 

controls the printing of messages by the message coordinator. The system administrator 
can control the size of the burst and the duration of the pause with this command 
(see "Notes"). 

CONTROL ARGUMENTS 

-count N, -ct N 

sets the size of a message burst to N messages. N must be a decimal integer 
greater than zero. (Default* 20 messages) 

-delay N, -dly N 

sets the interval between message bursts to N seconds. N must be a decimal 
integer greater than zero. (Default 5 seconds) 

-print, -pr 

displays the current message burst size and delay values. 
Execute this command in admin mode. You can include it in the $ystem_start.up.ec. 
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Ms.iii£t S€t mGS p olling time 

SYNTAX AS A COMMAND 
set_mos_pol 1 ing_time {N} 
FUNCTION 

sets the time interval used by the system for polling MOS memories to check for and 
log EDAC errors. 

ARGUMENTS 

N 

is a decimal integer representing the time in minutes between MOS memory polls. 
If omitted, the command prints the current polling interval. If N is 0, MOS 
memory polling is disabled. 

ACCESS REQUIRED 

You must have re access to hphcs_. 

NOTES 

MOS memory polling is disabled when the system is initialized. Use this command to 
enable it 

MOS memory polling should not be enabled on systems that have core memories 
unless the TEST/NORMAL switch on the maintenance panel of the memory, not of 
the controller, is set to TEST. If this switch is set to NORMAL, spurious errors may 
be logged for the memory. 



Name: set__proc_reqiiired, sprq 
SYNTAX AS A COMMAND 
I sprq {tagl} . . . {tag2} . . . {tagN} {-control_arg} 

FUNCTION 

restricts processes to run only on specified CPUs. You can use it to specify the set 
of CPUs on which the invoking process can be run and the default set of CPUs for 
all proc^i^ that have not rsQussted sp^f ic CPUs. 
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ARGUMENTS 
tagN 

is the tag for one of the CPUs in the group being specified. It can be one of 
the letters a through h, or A through H. If you give no tag, the group is 
assumed to contain all CPUs (tags a through h). If you give -priv, at least one 
tag is required. 

CONTROL ARGUMENTS 

-priv 

indicates that the group of CPUs specified is to become the default group for 
processes that have not requested specific CPUs. If omitted, the group of CPUs 
specified applies only to the invoking process. 

ACCESS REQUIRED 

You need access to phcs_. If you give -priv, you need access to hphcs_. 
NOTES 

If none of the CPUs specified are online, an error message is printed and the 
command has no effect 

EXAMPLES 

The command line 

set_proc_required A B 
restricts the requesting process to run only on CPUs A and E 
The command line 

set_proc_requi red 
allows the requesting process to run on any online CPU. 
The command line 

set_proc_requlred ABE -priv 

restricts all processes that have not requested specific CPUs to run only on CPUs A, 
B, and £. 

The command line 

set_proc_required -priv 

allows all processes that have not requested specific CPUs to run on any online CPU. 
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Name: set ^process^audit flags 

SYNTAX AS A COMMAND 
set_process__aud i t_f 1 ags {f 1 ags_str} 

FUNCTION 

sets the process security audit flags to the supplied value, turning on the specified 

flags and off all others. 

ARGUMENTS 
flags_str 

is an audit flags string acceptable to convert_access_audit.flags_. If you omit it, 
the command enters a prompt loop in which you are asked for an audit flags 
string. A period entered alone on a line causes the loop to exit 

ACCESS REQUIRED 

You must have re access on system_privilege_ and access_audit _gate_ and r to 
>udd>SysAdmin>admin>sys_admin_data if you use the **default" keyword. 

NOTES 

For a description of the process audit flags, see the new.user command in this section 
and the section "Security Auditing" in the System Administration Procedures (AK50). 

This command is meant for experimentation with security audit control flags by the 
system security administrator. Permanent settings for processes should be placed in the 
appropriate PNT/SAT entries with the new_user and edit_proj commands. 

The special keywords "none," "all," and "default" are also recognized for the audit 
flags string. They specify 



"none" all audit flags turned off 
"all" all audit flags turned on 

"default" audit flags set to default found in sys_admi n__data. 



See also the display.process_audit.f lags and edit_process.audit_flags commands. 
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EXAMPLES 

set_process_aucli t_f lags default 
d i spl ay__process_aud i t_f 1 ags 

f sob j=N/R,fsattr«N/R,rcp=N/R,admin«R/R, spec ial«R/R, . . . 

. . .other^N/R.admin^op.priv^optfaul t,^smal l^cc.'lnoderate^cc 

set_process_aud i t__f 1 ags rcp=n/r , adm i n=f /, spec i a 1 ^/r 

display_process_audl t_f lags 

f sobj=N/N , f sattr=N/N , rcp«N/R , adm i n=R/N , spec i a 1 *N/R, . . . 

. . .other=N/N,'^admin_op,'^pr iv_op, ''fault, '^smal l_cc,'^oderate_cc 

set_process_aud i t_f 1 ags def au 1 1 

current flags: f sobj=N/R,fsattr«N/R,rcp*N/R,admln«R/R, . . . 
. . .spec ial=R/R,ot her «N/R,admin_op,priv_op, . . . 
... f aul t.'^smal l^cc'^oderate^cc 
enter flags: fsobj=r/ 

new flags: fsobj=R/R,f sattr=N/R,rcp«N/R,admin=R/R, . . . 
. . .special*R/R,other=M/R,admin_op,pr lv_op, ... 
. . .faul t.'^smal l__cc,'^oderate_cc 
enter flags: fsobj=/m 

new flags: f sobj«R/M,f sattr«N/R, rcp«N/R,admi n«R/R, . . . 
. . . spec ?al=R/R,other«N/R, adm in_op,priv_op, . . . 
... f aul tj'^smal l__cc,'^oderate_cc 
enter flags: '^admi n_op,'^f aul t,other=ma/ma 
new flags: f sobj«R/M, f sattr«N/R, rcp=N/R,admi n«R/R, . . . 
. . . spec i a 1 =R/R , other«MA/MA , ^adm i n__op , pr i v_op .... 
... ^faul t,^smal l^ccj'^oderate^cc 
enter flags: 



Name: set^quota, sq 

SYNTAX AS A COMMAND 

sq pathi quota 1 {... pathN quotaN} 

FUNCTION 

sets the segment record quota of a specified directory, without affecting, or 
being limited by, the quota of the superior directory. It is intended for use 
on the root directory only. 

ARGUMENTS 

pathN 

is the name of the directory on which the quota is to be set 
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I quotaN 

is the quota in 1024-wor(i records to be set on the directory. 
ACCESS REQUIRED 

You need access to hphcs_. You need no permission in the directory whose 
quota is being seL 

NOTES 

No need that the new quota be greater than the current number of records being 
used by this directory. This command attempts to set a terminal quota even if 
it is set to zero. It does not update the inferior counts of the superior 
directory. Use it preferably only on the root, and transfer quota to inferior 
directories using move.quota. 

EXAMPLES 

To set quota on the root directory to allow 50,000 words of storage, type: 
set_quota > 50000 
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Name: set sons volume 

SYNTAX AS A COMMAND 
set_sons_vo]ume path LVNANE 
FUNCTION 

sets the logical volume on which the segments of a directory reside. 

ARGUMENTS 

path 

is the pathname of the directory whose sons logical volume ID is to be set 

LVNAME 

is the name of the logical volume. 

ACCESS REQUIRED 

You need access to hphcs_. 

NOTES 

This is a highly privileged command, which defeats the normal quota management for 
logical volumes. Normally, this conmiand is only used in system_start_up.ec to set the 
logical volume for the directory >pdd. This operation is valid only on an empty 
directory. The usual method of creating a directory with a specific "sons logical 
volume** (a master directory) is to use the Multics create.dir command (see the 
Commands manual, AG92). 



Name: set special password 

SYNTAX AS A COMMAND 

set_specia1_password specia1_id {-control_args} 
FUNCTION 

sets the password required for special (restricted) activities. Use it only in the 
accounting^start_up exec.com. 
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ARGUMENTS 
special_id 

is the special activity identifier. Currently, only one such identifier is defined, as 
follows: 

operator_admin_mode 

specifies operator "admin" mode. 

CONTROL ARGUMENTS 

-none 

sets the specified identifier to have no password. (Setting a value of -none for 
operator_admin_mode permits admin mode to be entered without a password.) 

-password PASSWORD 

sets the password PASSWORD. 

-prompt 

queries you twice for the password. (Default) 



Name: set_system__audit_flags 
SYNTAX AS A COMMAND 
set_system__audi t_f lags -control_args 
FUNCTION 

sets the system parameters that control auditing of user access to system resources. 

CONTROL ARGUMENTS 

I -covert_channel auth, -cch auth 

specifies that operations that can be used as covert channels are to be audited. 
The value specified for auth must be a valid AIM authorization string. Sending 
processes whose authorization is greater than auth are audited. Receiving processes 
are audited regardless of authorization. (See "Notes on Covert CJiannels," below.) 

-no_covert_channel, -ricch 

specifies that auditing of covert channel operations is to be turned off. 

-no_successful_access, -nsa 

specifies that there is to be no auditing of successful operations. 

-no_unsuccessful_access, -nusa 

specifies that there is to be no auditing of operations on system resources that 
are denied by the system. 
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-successfuLaccess access^class, -sa access.class 

specifies that all successful operations on system resources are to be audited. Only 
those operations involving resources with an AIM access class equal to or greater 
than access_class are audited. 

-unsuccessfuLaccess access_class, -usa access.class 

specifies that all operations on system resources that are denied by the system are 
to be audited. Only those operations involving resources with an AIM access class 
equal to or greater than access.class are audited. 

ACCESS REQU/RED 

You need access to the highly privileged gate hphcs.. 
NOTES ON COVERT CHANNELS 

A covert channel is a means for passing information between two processes that is | 
outside of the normal system mechanisms for data transmission. The Multics operating 
system was enhanced to identify operations that could be exploited as covert channels. 
The information generated by -cch provides administrators with information concerning 
the processes and data involved in the operation. The Multics literature contains no 
description of those operations identified as pot^tially exploitable as covert channels. 

NOTES 

Some parameter settings can result in d^adation of system performance (for example, 
if you audit successful operations, including those involving resources with the lowest 
AIM access class). 

Because some system operations can be catagorized in more than one way, they can be 
audited in more than one way. For instance, a particular operation could be audited 
for successful access and as a covert channel. Additionally, the per-process audit flags 
(see ed_installation_parms) can be set for additional auditing of operations. 

This conmiand changes only those auditing parameters as specified in the control 
arguments. Other i^ameters are not modified. 

See also display_system_audit_f lags. 
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Name: set^system console 

SYNTAX AS A COMMAND 

set_system_console {conso1e__name} {-control__args} 

FUNCTION 

controls the configuration of system consoles. 

ARGUMENTS 

console_name 

is the name of the console as it is specified in the configuration deck. If don*t 
give it, the bootload console is assumed. 

CONTROL ARGUMENTS 

-crash 

specifies that the system should crash in case of console recovery failure, 
-reset 

forcibly resets the bootload console as well as the oc.data database. If the 
console specified by console_name is not the bootload console, no action is taken. 

-run 

specifies that the system should continue running in the event of console recovery 
failure. It overrides -crash. 

-state STATE 

changes the operational state of the specified console to STATE, where STATE 
must be one of the following: 

on 

makes the specified console the bootload console and the primary recipient of 
I/O. If a bootload console is currently assigned, it is made an alternate 
console. 

alternate, alt 

makes the specified console an alternate console. In case of a bootload 
console failure, the first alternate console that appears in the configuration 
deck is selected as the bootload console. 

io 

specifies that this console exists, but it is not to be used as an alternate 
console. If this is the bootload console, it is unassigned. 

inop 

specifies that this console is inoperative. If this is the bootload console, it is 
unassigned. 
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off 

specifies that this console is being deconf igured and should not be used by 
the console software. This state cannot be used for the bootload console. 

WARNING 

When the bootload console is deconf igured with the set_system_console command, 
Multics will crash if the Crash on Console Recovery Failure option has been selected, 
either by using the -crash control argument above or by presence of the ccrf 
parameter in the config_file. The following message will be printed: 

ocdcm_ (reconfigure): Bootload console deconf igured with CCRF set. 



NOTES 

If the bootload console's state is set to 10 or INOP and no other console is assigned 
as the bootload console, Multics will send subsequent output to the Message 
Coordinator. If no Message Coordinator is available, Multics will act with respect to 
the specification of the ccrf parameter. 

Although it is possible to run the system from the Message Coordinator, it is not 
recommended that sites run without an active bootload console for extended periods of 
time. During the period that there is no bootload, console sites will be restricted to 
running only those commands executable at an initializer terminal. Failure of the FNP 
to which the initializer terminal is attached while running without a bootload console 
could produce severe problems. 



Name: set system priv 

SYNTAX AS A COMMAND 

set_system_pr i V pr i vi 1 ege_namel { . . . pr i vi 1 ege_nameN} 
FUNCTION 

is used to turn on and off the system privileges that allow the process to function 
outside the restrictions of the AIM access controls. Whenever the privileges are turned 
on, the user must carefully check to ensure that his actions do not accidentally 
disclose information that was previously protected by the AIM access controls. 

The set_system_priv command is needed only if the site is using the AIM access 
controls. 
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ARGUMENTS 

privilege_namei 

may be any of a character string which is listed below. 

LIST OF CHARACTER STRINGS 

comm 

turn on communications privilege. 

dir 

turn on directory privilege. 

seg 

turn on segment privilege. 

ipc 

turn on interprocess communication (IPC) send/receive privilege, 
ringl 

turn on privilege for ring 1 subsystems. 

soos 

turn on security-out-of-service privilege. 

rep 

turn on privilege for RCP resource management 

If any of the above privilege_names is preceded by the character the 
corresponding privilege is turned off. All privileges not mentioned in the 
argument string remain unchanged. 

ACCESS REQUIRED 

The user must have access to the system_privilege_ gate to use this command. 
EXAMPLES 

set__system_pr i V dir ^seg ipc 

turns on directory and IPC privileges and turns off segment privileges. The soos and 
ringl privileges remain unchanged. 
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Name: set system search rules 

SYNTAX AS A COMMAND 
set__system_search_rul es path 
FUNCTION 

is a highly privileged command used in the initiahzer process to set the site's default 
search rules for all processes. 

ARGUMENTS 

path 

is the pathname of a default search rules segment (described below) created earlier 
by the system administrator. 

DEFAULT SEARCH RULES SEGMENT 

Each line in the default search rules segment may be either a keyword or the absolute 
pathname of a directory to be searched. The order of the lines in the default search 
rul^ segment giv^ the order in which the rules are applied by a user process. 

The valid keywords are: 
i n i t i ated_segments 

IC^IC^Idlv-lll^ Wll 

work i ng_d i r 
home_d i r 
processed! r 

The absolute pathname search rules and the keywords may be followed by one or 
more tags. Tags are single word identifiers chosen by the system administrator and 
used to categorize search rules into groups. They are spearated from pathname or 
keyword search rules by a comma. 

The user can find out the site-defined tags by issuing the get_system_search_rules 
command (described in the Multics Commands and Active Functions manual. Order 
No. AG92). For example, if the get_system_search_rules command returns the 
following: 

i ni t i ated_segments ,def aul t , f ast 
refer enc i ng_d i r ,def au 1 1, fast 
working_di r ,def aul t, fast 

>system_l ibrary_standard,def aul t, fast, system_l ibraries 
>system_l i brary_unbundl ed ,def aul t , f ast , system_l i brar i es 
>system__l i brar y__tool s ,def aul t,system__l ibrar ies 
>system_l i brary_auth__ma I nt ,def aul t , system_l ibrar i es 
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the user knows there are three tags he can specify in his search rules: default, fast, 
and system_libraries. For convenience, the user can use these tags in his own search 
rules rather than specify the entire list of directories and keywords containing these 
tags. For example, the syslem_libraries tag in the user's search rules expands to: 

>system_l i brary_standard 
>system_l ibrary_unbundled 
>system_l ibrary_tools 
>system_l ibrary_auth_mai nt 

The order of the expanded list is the same as the order of the directories in the 
default search rule segment Recursion is not allowed. 

Up to 10 tags and up to 50 search rules may be specified in the default search rules 
segment. 

A user process may specify up to 22 search rules. 
EXAMPLES 

Assume the system administrator has created a default search rules segment named 
site_rules that contains the following lines 

ini tiated_segments,defaul t 
ref erenc i ng_d i r ,def aul t 
work i ng_d i r , def au 1 1 

>system_l i brary_standard , def aul t, system_l i brar i es 
>system_l i brary_unbund 1 ed ,def au 1 t , system_l ibraries 
>system_l i brary_tool s,def aul t,system_l ibrar ies 
>system_l ibrary_auth__mai nt,def aul t,system__l ibrar ies 

To set the site's default search rules for all processes, the system administrator types: 
set_system_search_rules si te_rules 



Name: set timax, stm 

SYNTAX AS A COMMAND 

stm N 

FUNCTION 

sets the maximum value that ti (time since interaction) can assume for an interactive 
process. 
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ARGUMENTS 
N 

is the number of seconds, in decimal, to which timax is to be set. A value less 
than or equal to zero causes it use the default timax from tc_data$timax. 

ACCESS REQUIRED 

The user must have access to both the privileged and the highly privileged gates phcs_ 
and hphcs_. 

EXAMPLES 

The command line: 

stm 3 '5 

sets timax to 3500000 microseconds for the current user's process and prints 
appropriate messages on both the user's terminal and operator console. 

The command line: 
stm 0 

sets timax to the default timax and prints messages on the user's terminal and operator 
console. 



Name: set ^tpp, stpp 

SYNTAX AS A COMMAND 

stpp directory {-centre i_args} 

FUNCTION 

prints and modifies the time-page product (tpp) of a specified directory. It should be 
used if the charge_disk command reports an inconsistency between the total tpp for a 
project, as recorded in projfile, and the total tpp for that project, as comput^ from 
the tpps of the project's directories. (This should be done only after it has been 
determined that the figure in projfile is the correct one, and the tpp of some 
directory was damaged.) 

ARGUMENTS 

directory 

is the pathname of the directory whose tpp is to be printed or modified. 
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CONTROL ARGUMENTS 

-directory, -dr 

print or modify the tpp for directory pages. 

-long, -Ig 

print the current tpp and its equivalent dollar charge, plus the quota, pages used, 
time tpp last updated, sons logical volume identifier, and quota switch. 

-print, -pr 

print the current tpp and its equivalent dollar charge, 
-segment, -sm 

print or modify the tpp for segment pages. This is the default, 
-set N 

modify the tpp as specified by N. See "Notes" below for the possible formats of 
the N value, and more details on the functioning of the set operation. 

NOTES 

If none of the arguments: -print, -long, or -set is given, -print is assumed; more 
than one may be given. 

The N value given with the -set control argument may be in units of page-seconds or 
dollars and . cents, a leading dollar sign ($) indicating the latter. Value may be an 
absolute value or a relative value (i.e., a change to be applied to the current tpp), a 
leading plus (+) or minus (-) sign indicating the latter. When both a dollar sign and a 
plus or minus sign are given, they may appear in either order. No blanks may appear 
between the signs and the numeric value. 

When an absolute value is given for N, the setting of that value is only approximate. 
The equivalent change from the current tpp is computed, and then applied as a 
change; since the tpp of an active directory is updated frequently by the storage 
system, the resulting tpp, after this change is applied, is larger tiian Uie specified value 
by the number of page-seconds that have accrued during the execution of the 
command. Use of the relative form of the value argument is recommended over the 
absolute form. 

When the -set control argument is specified, the size and direction of the change and 
the (approximate) resulting new value are computed and displayed, in both page-seconds 
and dollars, and the user is asked if the change should actually be made. If the 
answer is yes, the change is made and then the actual resulting new value is printed. 
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EXAMPLES 

! set tpp >udcl>sa -print 

tpp=5 138695885 ($1189.51) 
! set_tpp >udd>sa -set $+2.01 

set_tpp: This operation will INCREASE the segment page charge on >udd>sa 
by $2.01 to 51^7392077 ($1191.5M. Do you want to do that? 
! yes 

tpp is now 51i*7^08682 ($1191-55) 

! set_tpp >udd>sa -set $-2.01 

set_tpp: This operation will INCREASE the segment page charge on >udd>sa 
by $2.01 to 51^0898662 ($1190.02). Do you want that? 
! yes 

tpp is now 51^0913009 ($1190.03) 



Name: set work class, swc 

SYNTAX AS A COMMAND 
swc wc_number {id} 
FUNCTION 

moves a process or set of processes from one work class to another without installing 
a revised master group table (MGT). The effect of this command is temporary since 
the answering service recomputes and resets a process' work class if the shift changes, 
a new MGT is installed, the user issues a new_proc command, or the operator issues 
the "maxu auto" command. 

ARGUMENTS 

wc_number 

is the number of the work class to which processes are to be moved. 

id 

may be a User_id or a process identifier. If a User_id is given it must be of 
the form Person. Project tag, and any or all components may be "*". If a process 
identifier is given it must be an octal number. If this argument is not given, 
only the process executing the command is moved to the specified work class. 
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ACCESS REQUIRED 

This command requires access to hphcs_. Additionally, this command requires read 
access to one or more system tables if the person_id.project_id.tag option is used. If 
the tag specified is "a" or "*", access to the answer_table is required. If the tag 
specified is "m" or "*", access to the absentee_user_table is required. If the tag 
specified is "z" or "*", access to the daemon_user_table is required. All of these 
tables are located in the directory >system_control_l. 

NOTES 

In order to prevent severe errors, set_work_class never matches any User_id to the 
Initializer process. If for some reason it is necessary to move the Initializer out of 
work class zero, this must be done by specifying the Initializer's process identifier. 

EXAMPLES 

The following are examples of valid command lines: 
swc 1 '< . . * 

moves all processes to work class 1. 
swc 2 *.SysDaemon=2 

moves all processes with the SysDaemon Project_id and the tag of "z" to work class 
2. 

swc 3 *-*.m 
moves all absentee process to work class 3. 
swc k 

moves the executing process to work class 4. 



Name: set x25 packet threshold 

SYNTAX AS A COMMAND 

set_x25_packet_threshold channel_name packet^size 
FUNCTION 

sets the minimum size of X.25 "long" packets. Packets of this size or larger are given 
lower priority than short packets. 
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ARGUMENTS 

channel_name 

is the name of an X.25 multiplexer channel. 

packet_size 

is the minimum length of a long packet, in characters. 
ACCESS REQUIRED 

Use of this command requires access to the hphcs_ gate. 
NOTES 

If packet_size is set larger than the maximum packet size in use by the multiplexer, 
no packets are given preferential treatment on the basis of size. The initial value of 
the minimum long packet size is determined by the "packet_threshold" parameter in 
the terminal type definition for the multiplexer. The present value of the parameter, 
and the maximum size for all packets, is included in the output from the tty_dump 
command. 



Name: sort projfile 

SYNTAX AS A COMMAND 
sort__projf i le {path} 
FUNCTION 

sorts the entries of the projfile segment into the order required by the billing 
programs. The sort is by Project_id. 

ARGUMENTS 

path 

is the pathname of the projfile segment The default is the segment projfile in 
the working directory. 
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Name: sort reqfile 

SYNTAX AS A COMMAND 
sort_reqfile {path} 
FUNCTION 

sorts the entries of the reqfile segment into the order required by the billing 
programs. The major key is the account number and the minor key is the requisition 
number. 

ARGUMENTS 

path 

is the pathname of the reqfile segment. The default is the segment reqfile in the 
working directory. 



j Name: smiimarize_sys__log, ssl 

[ SYNTAX AS A COMMAND 

I ssl {log_selector} -control control_path {-control_args} 
I FUNCTION 

summarizes activity in a system log. The specified range of messages in the log are 
matched against the selection and printing criteria in the control file and written or 
summarized to the specified I/O switches. This command requires that a set of I/O 
switches (used to write log messages and summaries) be attached before the command 
is executed and detached afterwards. Control arguments determine what range of 
messages are processed, and how those messages are formatted in the output 

I ARGUMENTS 

log_selector 

is the pathname of a log to be summarized The pathname must specify the first 
segment in the log. This argument is incompatible with any of the log selection 
control arguments. 

t CONTROL ARGUMENTS FOR LOG SECTION 

-pathname LOG_PATH, -pn LOG_PATH 

specifies the pathname of the log to be summarized, the pathname must specify 
the first segment in the log. This argument is incompatible with any of the other 
log selection control arguments, or an explicit log pathname. 
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-admin i 

specifies that the admin log is to be summarized. The admin commands log is i 

called "adminjog", and is located in the >scl>as_logs directory. This argument is i 

incompatible with any of the other log selection control arguments, or an explicit i 

log pathname. i 

-answering_service, -as i 

specifies that the answering service log is to be summarized. The Answering i 

Service log family is called "log", and is located in the >scl>as_logs directory, i 

This argument is incompatible with any of the other log selection control i 

arguments, or an explicit log pathname. i 

-dm_system, -dms 

specifies that the data management system log for the process's current AIM 
authorization is to be summarized. The data management log is called "dm_system_log", 
and its location depends on the AIM access class of the log. This argument is 
incompatible with any of the other log selection control arguments, or an explicit 
log pathname. Reading the log requires access to the dm_admin_ gate. 

-mc_log LOG_NAME, -mcl LOG_NAME | 

specifies that the message coordinator (daemon) log named LOG_NAME is to be | 

summaried. All message coordinator logs are located in the >scl>as_logs directory; i 

their names depend on the daemon to which they belong. This argument is i 

incompatible with any of the other log selection control arguments, or an explicit i 

log pathname. i 

— syserr i 

specifies that the syserr log is to be summarized. The syserr log is named i 

"syserr_log". The first segment in the family is >sll>syserr_log; there may be a i 

history segment in >sll, and older history segments are in the directory i 

>scl>syserr_log. This argument is incompatible with any of the other log selection i 

control arguments, or an explicit log pathname. i 

CONTROL ARGUMENTS FOR CONTROL | 

-control CONTROL_PATH 

specifies the pathname of the selection control file to be used in summarizing the 
log messages. See "Control File Syntax" and "List of Selection Operators", below 
for details of the syntax. This argument must be specified. 

-from TIME, -fm TIME, -from NUMBER, -fm NUMBER | 
specifies that the first message processed is the first message at or after the 
specified time or sequence number; if -reverse is specified, the first message is 
the one at or before the specified value. If no -from value is specified, the 
default is the first message in the log, or the last if -reverse is specified. This is 
incompatible with -last. 
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I -to TIME, -to NUMBER 

I specifies the last message to be processed, either by message time or sequence 

I number. If not specified, the default is all the remaining messages in the log. 

I This is incompatible with -for. 

I -last NUMBER, -It NUMBER, -last TIME, -It TIME 

I specifies that only the last NUMBER messages, or the messages since TIME, are 

I to be processed. If a NUMBER is specified, it specifies the actual number of 

I messages to be processed, not the number of messages examined in the log. This 

I is incompatible with -from and -for. 

I -for TIME, -for NUMBER 

I specifies a number of messages to process, or a time interval relative to the 

I starting time (specified by -from) in which the messages must be contained. The 

I number of messages is the actual number of messages processed, not the number 

I of messages examined in the log. This is incompatible with -to and -last. 

I CONTROL ARGUMENTS FOR MESSAGE EXPANSION 

I -octal, -oc 

I specifies that the binary data in expanded messages is to be displayed in octal, 

I rather than, or in addition to, the interpreted representation. If both octal and 

I interpreted representations are desired, both the -octal and -interpret control 

j arguments must be supplied. 

-interpret, -int 

specifies that the binary data in expanded messages is to be displayed as 
interpreted text, by calling the appropriate expand_XXX_msg_ program for the 
data class of the message. If the -octal control argument is also specified, the 
binary data is displayed both in interpreted form and as octal data. This is the 
default 

I CONTROL ARGUMENTS FOR MESSAGE FORMAT 

-linejength N, -11 N 

specifies the line length used when formatting message text and data for printing. 
The value (N) must be between 25 and 500. By default, it is the line length 
associated with the user_output I/O switch, or, if none (as for an absentee), it is 
132 (for line printer output). 

I -indent N, -ind N 

I specifies that all messages are to be formatted for printing prefixed with N 

I spaces. The value of N must be between zero and fifty. The indentation is 

j printed before any data associated with the message, including the message prefix. 

I By default, there is no indentation. 
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-continuation_indent N, -ci N i 

specifies that all messages are to be formatted for printing with continuation lines i 

prefixed by N spaces, or, if the keyword "standard" or "std" is used in place of i 

a number, with the continuation lines indented sufficiently to line up under the i 

first character of the text of the message. The value of N must be between zero i 

and fifty. By default, continuation lines are indented to the "standard" i 

indentation. i 

-prefix STRING, -pfx STRING | 

specifies that all messages are to be formatted with the specified string as a i 

prefix. This prefix appears after the indentation (if any was specified). The i 

prefix must explicitly include trailing spaces, if any are desired to separate the i 

prefix from the message text. By default, there is no prefix. i 

-duplicates, -dup i 

inhibits the printing of "=" messages for messages whose text is the same as the i 

previous message printed. All messages are printed exactly as they appear in the i 

log- ~ I 

-no_duplicates, -ndup i 
prints "==" for messages whose text is the same as the previous message printed, i 
This is the default. i 

-date_format FORMAT.STRING, -dfmt FORMAT_STRING 

specifies a date/ time format string (see time_formaLgi.info or the Multics 
Programmer's Reference Manual, Order No. AG91) to be used when formatting 
the date when successive m^sages are printed with different dates. The date 
string is printed on a line entirely by itself, preceded by a blank line. If the 
date format string is blank, no date separators will be printed; this should be 
used if a -time_format string is specified that includes the date as well. The 
default date string is "'^9999yc-'^my-^dm ^da ^za", which prints as (for example) 
"1984-10-31 Wed est". 

By specifying null strinp for date, time, and number formats, the log can be j 
printed and saved, so that it can be compared to another log script later, without j 
spurious mis-compares because the times and sequence numbers do not match. | 

-time.format FORMAT.STRING, -tfmt FORMAT.STRING 

specifies a date/ time format string (see time_formatgi.info or the Multics 
Programmer's Reference Manual, Order No. AG91) to be used when formatting 
the message time portion of the message. If the string is null, no time is printed 
with the messages. The default time format is "iso_time", which prints as (for 
example) "23:21:59". 

-number_format IOA_STRING, -nfmt IOA_STRING 

specifies an ioa_ string to be used when printing the sequence number for the 
message. If the string is null, no sequence number is printed with the message. 
The default is "'^Td". (See the Multics Subroutines and 110 Modules manual. 
Order No. AG93 for a description of ioa_control strings.) 
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MISCELLANEOUS CONTROL ARGUMENTS 

-procedure NAME, -proc NAME 

specifies that en try points in the procedure called NAME are to be used instead of 
entrypoints in log_read_ to read the log. This is used to read logs protected by 
inner-fing subsystems, where the inner-ring subsystem provides a replacement 
log-reading procedure. See "Access Required," below. 

NOTES 

The summarize_sys_log command produces multiple copies of printable files, each 
containing different abstracts of the log being scanned. There are two basic abstracting 
techniques: writing lines selected by character string matching into the file, and 
writing the total number of occurrences of specified types of lines. 

There are two possible methods for specifying the starting point of an invocation of 
th^ sys_log_scan_report command. The recommended method is to use a value segment 
to record the times, as follows: 

vs first^entry [clock ca 1 endar_cl ock [vg last_entry] +lusec] 

vs last_entry [clock cal endar_clock] 

ssl LOG_PATH -from [vg first_entry] -to [1 ast__entry3 



NOTES ON OUTPUT 

Rather than writing directly into files, the command writes its output through 
user -specified I/O switches. No I/O switch attachment or detachment is done by the 
program. It is the responsibility of the caller to ensure that all switches named in the 
control segment are attached and opened with the io_call command. Usually, these are 
attached to storage system segments through the vfile_ I/O module. 

NOTES ON CONTROL FILE SYNTAX 

The control file names the output switches and selection operations used by the 
command. The general format of a control line in the file is: 

SWITCHNAME, SEVERITY, OPCODE, LITERAL. 

switchname 

is the name of an I/O switch to which this information will be written. 

severity 

indicates the minimum severity message this control line applies to, or a range of 
severities. The severity value may either be a decimal integer, or ranges consisting 
of a pair decimal integers separated by a colon ("20:29"). 
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opcode 

describes the kind of selection desired. It may have any one of the values listed 
below: 

all 

selects all lines. 

any 

selects any lines containing the string <literal>. 

allx 

like all, but messages with binary data have the data expanded when printed. 

anyx 

like any, but messages with binary data have the data expanded when printed, 
bcount 

counts all lines that begin with the string <literal> and places the total on 
the named switch after all entries are written. 

begin 

elects all lines with the string <literal> as their beginning, 
beginx 

like begin, but messages with binary data have the data expanded when 
printed. 

count 

counts all lines that contain the string <literal> and places the total on the 
named switch after all entries are written. 

nbegin 

diverts any lines that begin with the string <literal> from the output switch 
if later selected by an all, any, or begin opcode. 

not 

diverts any lines that contain the string <literal> from the output switch if 
later selected by an all or begin opcode. 

To be effective, the not and nbegin lines for a particular switch may precede 
the all, any, and begin control lines. The not and nbegin lines do not affect 
the counting of lines. If no lines were written on a switch, and a count is 
zero, the total line is omitted. 

If any lines were written on a switch, a count of total lines written follows 
the totals for count and bcount. Thus, nothing is written on a switch only if 
all selections fail. 
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I literal 

I is an operand used to select the message; its function is described individually for 

I each opcode. All characters following the comma are taken literally; no quote 

I processing is performed. 

I ACCESS REQUIRED 

For all except inner-ring logs, read permission is required on the log segments 
themselves, and status permission is required on their containing directories. If an 
access error is encountered searching for older history logs, the search is stopped at 
that point, and no further history will be available. For the logs selected by control 
arguments, the control argument descriptions list the standard history directories for 
the logs. 

For inner-ring logs (the data management system log is the only standard inner-ring 
log), access to the logs is required, as is access to the gate used by the log-reading 
procedure (see -procedure). 

I NOTES ON SEVERITY VALUES 

I Severity values in log messages are used to indicate the importance of the message 

j being logged, in a general way. Most logs use increasing severity to indicate increasing 

j importance, but the actual meaning depends on the log. For the Answering Service 

j and M^sage Coordinator logs, the severities have the following meanings: 

0 => Message just logged 

1 => Message logged and printed on a console 

2 => Message logged and printed on a console with bells 

3 => Message logged, printed, and the system crashed 

I For the syserr log, the severities have different meanings: 

0 => Message logged and printed on syserr console 

1 => Message logged, printed, and the system crashed 

2 => Message logged, printed, and the process writing the 

message is terminated. 

3 => Message logged and printed, and console alarm sounded 

k => Message just logged, or printed if logging mechanism is 
i noperabl e 

5 => Message just logged, or discarded if it can't be logged 

The severities 20 to 25 are handled just like 0 to 5, but are different to indicate that 
the originating program was writing an access audit message, rather than just an 
informative message. 
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NOTES ON INNER-RING LOGS 

Some applications create logs in an inner ring that must be read using a special 
interface. The only standard log to do this is the Data Management system log, and it 
is read by specifying the -dm_system control argument which supplies both the 
pathname and the procedure name (dm_log_read _). Other applications may provide 
their own special procedures for log reading, in which case both the log pathname and 
the procedure name must be supplied explicitly via the -pathname and -procedure 
control arguments. Note that a log read using a reader procedure may enforce 
additional access requirements as well as requiring access to the log itself. In 
particular, the user must have access to the reader procedure. 



Name: sweep i 

SYNTAX AS A COMMAND i 

sweep {path} {-control_args} i 

FUNCTION I 

obtains the disk usage figures for the hierarchy, or any specified subtree, and places i 

them in a segment for subsequent use by accounting and disk usage analysis tools. By i 

default, the segment is named disk_staL It is not an ASCII segment, and the i 

disk_stat_print command must be used to print its contents. i 

ARGUMENTS i 

path I 

is the pathname of the directory at which the sweep is to start. The usage i 

figures for this directory, and for the entire subtree beneath it are recorded. If i 

path is omitted, the sweep begins at the root directory. See "Notes" below. | 

CONTROL ARGUMENTS | 

-brief, -bf 

does not print an error message when unable to force access to a directory to 
read its usage figures. This is the default 

-long, -Ig I 

prints an error message if unable to force access to a directory. | 

-output_file XX, -of XX | 

places the output in the specified segment XX rather than in the default segment, | 

named disk_stat, in the working directory. i 
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-pdd 

do not exclude >pdd from the sweep. By default, a sweep that starts at the root 
deliberately omits >pdd. This argument is not used in the accounting application 
of this program, but it may be used during an analysis of disk space usage, when 
complete and accurate total page usage figures are desired. The initializer process 
must first be used to give sma access to >pdd to the process that will run the 
sweep. 

I NOTES 

The figures recorded in disk_stat are the quota, records used, and time-record product 
(trp). These figures are recorded separately for segment pages and directory pages. 

Since directories with zero quotas have their record usage and trp figures included in 
those of the first superior directory with nonzero quota, it is not necessary for sweep 
to walk the entire hierarchy. Instead, whenever it encounters a directory with a zero 
quota, it goes no further down in that particular branch, but instead goes on to the 
next directory at the same level. This applies separately to segment and directory 
quotas. 

I Therefore, any directory whose usage figures are to be recorded separately for 
i purposes of accounting or disk usage analysis must be given nonzero segment and 
I directory quotas. It is recommended that at least all directories immediately inferior to 
I the root and all project directories under >udd be given nonzero segment and 
1 directory quotas. 

I Project administrators may use this command to obtain detailed information about the 
I disk usage of a project's users by executing sweep with the project directory pathname 
I as the first argument. This is possible, however, only if the users' home directories 
I have nonzero quotas. 

I EXAMPLES 

I sweep >udd>Alpha -output__f i le Alpha. di sk_stat -long 

I places disk usage information for the Alpha project directory and all directories 

I beneath it with quotas in the segment Alpha. disk_stat, and prints an error message if 

I unable to force access to any directory. Alpha. disk_stat can then be printed using the 

I disk_stat_print command. 
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Name: sweep pv 

SYNTAX AS A COMMAND 
sweep_pv pvname {-control_args} 
FUNCTION 

performs utility functions that require walking through the VTOC of a mounted 
physical volume. Among these functions are the listing of contents and unconnected 
VTOCEs, the deletion of such VTOCEs, and the evacuation of physical volumes (for 
logical volume compression). The volume is processed in VTOC order. 

ARGUMENTS 

pvname 

is the name of the mounted physical volume v^^hose VTOC is to be walked 
through. 

CONTROL ARGUMENTS 

-adopt 

attempts to reconstruct directory branches for VTOCEs encountering reverse 
connection failures. Unique names are derived from the primary name in the 
VTOCE. The -gc control argument must be given to use the -adopt control 
argument. If the -dl control argument is given as well, VTOCEs that cannot be 
adopted are deleted. The success or failure of adoptions is reported to the report 
produced by the -gc control argument. For a description of the definition 
attributes provided for adopted branches, see the description of the adopt_seg 
command. This request requires hc_backup_ access. 

-debug, -db 

is for system programmer use, and disables highly privileged calls in order to 
allow debugging of this program. 

-delete, -dl 

deletes unconnected VTOCEs. This control argument is only allowed when the -gc 
control argument is specified. Access to hphcs_ is required to use this control 
argument. The collection report is modified to indicate that these VTOCEs were 
deleted. 

-force, -fc 

forces access to all directories that need to be scanned where status permission is 
lacking. Status permission is necessary for all components of the pathnames of 
VTOCEs processed. If this control argument is not used, or status permission is 
lacking and cannot be forced, an error is reported. 
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-from first 

indicates the first VTOCE to be processed. If first is not given, VTOCEs are 
processed starting at VTOC index 0. 

-gc 

performs garbage collection, i.e., all VTOCEs for which a reverse connection 
failure is encountered in resolving their pathnames are logged in a collection file. 
This file is produced whether or not the -list control argument, above, is 
specified. At the end of the collection file report, the total number of VTOCEs 
and records held by them in this state is printed. Selected information, such as 
the name in the VTOCE and date/time used and modified, is also put in the 
report for each such VTOCE. The collection file report is given a three-component 
name and is placed in the working directory. The three-component name has 
"pvgc" as the first component, the physical volume name as the second, and the 
time the segment is created as the third component (e.g., pvgG.public.0814). 

-list 

creates a listing file containing the VTOC index, time listed, and pathname of 
every segment on the volume at the time its VTOCE is scanned. An asterisk on 
the line of the listing for a particular VTOCE indicates a reverse connection 
failure (i.e., no branch exists for the entry). For nondirectory segments, the page 
fault meter of the segment is given. The convention for listing incomplete 
pathnames is the same as that used by the vtoc_pathname command (see the 
vtoc_pathname description in the Multics Commands and Active Functions 
manual. Order No. AG92). The listing file is given a three-component name and 
is placed in the working directory. The three-component name has "pvlist" as the 
first component, the physical volume name as the second, and the time the 
segment is created as the third component (e.g., pvlist.public.0749). 

-move, -mv 

moves all segments corresponding to VTOCEs processed off this volume onto 
another physical volume of the same logical volume. Segments that suffer reverse 
connection failures are not moved. If segments are moved for some purpose other 
than evacuation, the inhibit_pv command should be invoked with the -off control 
argument after moving has taken place. The sweep_pv command attempts to target 
segment moves to the physical volume in the logical volume with the most page 
space available by inhibiting and disinhibiting volumes dynamically; all volumes 
except the volume being evacuated are disinhibited when the sweep_pv command 
is exited. Volumes found to be inhibited at the time the command is invoked are 
not disinhibited; this facilitates simultaneous evacuation of volumes. Any volume 
that is completely evacuated by this means should be deregistered before the 
logical volume is reaccepted. Access to the hphcs_ gate is required to use this 
control argument. (See the Multics System Maintenance Procedures manual. 
Order No. AM81, for more details.) 

-only vtocx 

processes only the single VTOCE whose octal index is vtocx. 
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-to last 

indicates last VTOCE to be processed. If last is not given, processing proceeds to 
the end of the VTOC. 

ACCESS REQUIRED 

The sweep_pv command requires phcs_ access, access to hc_backup_ if the -adopt 

control argument is used, and access to hphcs_ if the -delete or -move control 
arguments are used. 

NOTES 

Any errors encountered during the VTOC sweep are reported to a file that is given a 
three-component name and placed in the working directory. The three-component 
name has "pvef" as the first component, the physical volume name as the second, and 
the time the segment is created as the third component (e.g., pvef. public. 1321). Errors 
in command usage, such as specifying a nonexistent or unmounted physical volume, are 
reported to the bootload console. 

When sweep_pv is invoked with the -move control argument, it first inhibits segment 
creation on the volume being vacated, and then vacates the pack. When sweep_pv 
terminates, it leaves the volume inhibited and prints a message to this effect. The 
volume can be uninhibited manually by means of the inhibit_pv command. 



Name: sys full report 

SYNTAX AS A COMMAND 

sys_f ul l__report {logl ]og2 ... logN} {-contro]_arg} 
FUNCTION 

is used by the crank in master.ec to update, and by biller.ec to print, the contents of 
a segment containing a history of all instances where a user was refused login because 
the system was full. 

ARGUMENTS 

logi 

is the pathname of a system log segment. 
CONTROL ARGUMENTS 
-print 

print the contents of the segment 
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NOTES 

The history is kept in the segment sys_full_report_seg in the working directory 
(normally >udd>SysAdmin>admin). This segment is created if it does not exist. 

If given, the -print control argument must be the last, or the only, argument. The 
crank (in master.ec) invokes this command with the name of just one log segment at 
a time; the biller.ec segment invokes it with just the -print control argument. 



Name: system comm meters 

SYNTAX AS A COMMAND 
system__comm_meters {-control _args} 
FUNCTION 

prints out metering information for ring zero Multics Communications Management. 

CONTROL ARGUMENTS 

-report_reset, -rr 

prints metering information and then resets the metering interval. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 
the last call with -reset specified. The metering information is not printed. If 
-reset has never been given in a process the interval begins at system initialization 
time. 

NOTES 

Use of the system_comm_meters command requires access to the metering. gate, and 
phcs_ gates. 
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EXAMPLES 

The following is a sample of the output of the system_comm_meters command. 
Total metering time 05:^3:27 



THROUGHPUT 

Total characters input 
Total characters output 
Average length of input 
Average length of output 
Input characters preconverted 



Number of ca 1 1 s 
Average time per call 
Average chars, processed 
Average chars, per msec. 
CHANNEL INTERRUPTS 



before conversion after conversion 
17, 23^^,567 15,5^3.210 
168,012,3^5 185,876.5^3 
12.3 characters 
59=7 characters 
20,i435 (1 .2% of total) 



read 

l.W,789 
6.37 msec. 

13.5 
2.1 



software "interrupts" 
average time (msec.) 



i nput 
678,901 
1.3^ 



output 
lt23,A40 
0.56 



wr i te 
26,357,924 

9.63 msec. 
57.8 

5.8 

other 
1 10,01 1 
0.23 



rat i o 

0. 90 

1. U 



total 
1,212,352 
1 .01 



TTY_BUF SPACE MANAGEMENT 

Total size of buffer pool 
Number of channels configured 
Number of multiplexed channels 

% of buffer pool in use 
i nput 
output 

control structures 



11,480 words 

143 
8 

current 
6.9 
13.4 

15.8 



average 

6.5 

15.6 

15o3 



total 

Smallest amount of free space ever 



36.1 37.4 

4,358 words (38% of buffer pool) 



a 1 1 ocate 

Number of calls 24,657,988 
Average time per call (msec.) 0.23 
% of total CPU 0.14 
Calls requiring loop on tty_buf lock 
Average time spent looping on lock 
Number of allocation failures 



free 
20,665,443 
0.37 
0.17 



total 
45,323.431 

0.29 
0.31 



1,249,340 (2.83% of total) 
0.14 msec. (0.01% of total CPU) 
0 (0.00% of attempts) 
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CHANNEL LOCK CONTENTION 



Number of calls to tty_lock 
Times channel lock found locked 
Average time spent waiting for lock 
Maximum time spent waiting for lock 
Number of interrupts queued because 
channel locked 



^0,392,817 
2,364,758 (5% of attempts) 
1 .8 msec . 
3.7 msec. 

25.437 (2.2% of interrupts) 



ECHO NEGOTIATION 

Average time of transaction 3.2 msec. 

Number of characters echoed by supervisor 21, 57^ (0.13% of input chars) 

Number of characters echoed by FNPs 335*466 (1.87% of input chars) 



ABNORMAL EVENTS 



Input restarts 
Output restarts 
Output space overflows 
"needs_space" calls 



12,576 (0.8% of read cal Is) 

304,289 (1.2% of write calls) 

16,384 (0.1% of write cal Is) 
0 



Name: system ^daily report 

SYNTAX AS A COMMAND 

system_da i 1 y_report today .use_tota 1 s yesterday ,use_total s 
FUNCTION 

prints a report of the system usage for the day just ending. 
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ARGUMENTS 
today. use_totals 

is a data base giving month-to-date usage information including the usage of the 
current day. 

yesterday. use_totals 

is the previous day's month-to-date usage segment. 

NOTES 

The day's usage totals are computed by subtracting the month-to-date totals in 
yesterday. use_totals from those in today.use_totals. This command is executed by the 
crank (in master.ec) and assumes that the two use_totals segments contain the 
information for the respective days, as suggested by their names. The information in 
these segments is placed there by the system_total and usage_total commands, also 
executed by the crank. 



Name: system link meters 

SYNTAX AS A COMMAND 

system_1 ink_meters {-control_arg} 

FUNCTION 

prints out system-wide statistics regarding usage of the Multics linker. Information is 
obtained from the active_hardcore_data and tc_data data bases. 

CONTROL ARGUMENTS 

-report_reset, -rr 

generates a full report and then performs the reset operation. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 
the last call with -reset specified. If -reset has never been given in a process, it 
is equivalent to having been specified at system initialization time. 

ACCESS REQUIRED 

This command requires access to phcs_ or metering gate . 
NOTES 

If the system_link_meters command is given with no control argument, it prints a full 
report. 
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Statistics are given for overall use of the linker, and are also broken down by task. 
The three major tasks of the linker are: 

1. Searching the definition section of the object segment for the symbolic name of 
the referenced segment. 

2. Searching for the segment using the standard search rules. 

3. Getting the linkage to the referenced segment. 

The following are brief descriptions of the variables printed out by the system_link_meters 
command. 

CPU Metering time 

is the amount of time for which the processor was busy. It equals total processor 
time minus idle lime. 

Total time in linker 

is the total amount of CPU time spent in the linker, expressed as hh:mm:ss. 

Average lime per link 

is the average lime to completion (in milliseconds) for a call to the linker. 

Percentage of real time in linker 

is the percentage of total metering time that was spent in the linker. 

Percentage of CPU 

is the percentage of virtual CPU metering time that was spent in the linker. 

Time Slot 

are the time slots into which calls to the linker are broken down. The four slots 
are for calls completed in less than 25 milliseconds, calls completed in between 25 
and 50 ms, calls completed in between 50 and 75 ms, and calls completed in 
more than 75 ms. 

Calls 

is the number of calls that were completed in each time slot. 
Total time in slot 

is the total amount of virtual CPU time taken by calls in each time slot 
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Percent total time 

is the percentage of the virtual CPU time spent in the linker that was taken by 
calls in each slot. 

Percent total calls 

is the percentage of calls to the linker that fell into each time slot. 

Average time 

is the average time (in milliseconds) to complete a call to the linker that ended 
up in , each time slot. 

Average page faults 

is the average number of page faults for a call in each slot. 

The following statistics are given for each of the three major tasks of the Multics 
linker: definition search, segment search, and get linkage. 

Average time 

is the average time (in milliseconds), for a call in each slot, spent on that 
particular function of the linker. 

Average page faults 

is the average number of page faults for a call in each slot, which occurred 
during that particular task of the linker. 

Percent time in slot 

is the percentage of the total time spent in the slot that was taken up by that 
particular task. These percentages do not add up to 100% because some time used 
by the linker does not fit into any of the three categories. 

EXAMPLES 

The following is an example of the information printed when the system_link_meters 
command is invoked with no control argument. (See Appendix A for a representation 
of the configuration deck used to create the system from which the metering sample 
was taken.) 



Linkage Meters: 

CPU Metering time 0:15:33 

Total time in linker 0:02:17 

Average time per link 5-83 msec. 

Percentage of real time in linker 14.78 

Percentage of CPU time in linker 3«l6 
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Time slot (msec) 


<25 


25-50 


50-75 


>75 


Calls 


22995 


569 


56 


51 


lOtal L 1 nic in 9 1 O L \J 


• n 1 • LL 


0 . on • 17 




n . nn . 1 i 


Percent total time 


76. 1 1 


12.88 


2.36 


8.65 


Percent total cal 1 s 


97. H 


2,40 


0.24 


0.22 


Average time 




31.21 


58.24 


233.93 


Average page faults 


0.21 


2.59 


5.55 


6.71 


Segment Search 










Average time 


2.37 


25.95 


48.39 


6.82 


Average page faults 


0.04 


1.12 


2.10 


0.04 


Percent time in slot 


56. 12 


82.81 


83.74 


2.88 


Get Linkage 




4.18 






Average time 


0.81 


8.04 


229. 12 


Average page faults 


0.07 


0.79 


1.95 


6.50 


Percent time in slot 


19.29 


13.35 


13.91 


96.69 


Definition Search 










Average time 


0.22 


0,24 


0.21 


0.19 


Average page faults 


0.02 


0.11 


0.15 


0.00 


Percent time in slot 


5.26 


0.76 


0.36 


0.08 



Name: system monthly report 

SYNTAX AS A COMMAND 

system_monthl y_report today .use_total s 1 ast_month .use_total s 
FUNCT/ON 

prints a report that shows system resource usage for the current billing period and 
percent changes from respective figures for the previous billing period. 

ARGUMENTS 

today. use_totals 

is the pathname of the month-to-date statistical data base. 
lasi_month. use_totals 

is the pathname of the copy of the statistical segment that was saved at the end 
of the previous billing period. 
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NOTES 

This command is executed by biller.ec as part of the monthly billing. 

The use_totals segments are created and initialized by the reset_use_totals command 
and updated by the system_total and usage_total commands. 



Name: system performance graph, spg 

SYNTAX AS A COMMAND 

spg sampl e_t ime {-control_args} 

FUNCTION 

generates a system of graphs that meter information concerning system performance 
and operation. The output can be directed to a file or to the controlling terminal. 
Periodically, metering information is presented in an output line. The initial line 
contains the cumulative values since system initialization. Whenever there is a change 
in system configuration or any of several parameters affecting system performance, an 
additional line noting the change is issued before the sample line. In this way, a 
system of graphs is developed where various metered quantities are plotted against 
time. Because the sampling is implemented by means of an event call channel, it is 
possible to use the terminal in a restricted way for other purposes while metering is 
in progress. All output is produced on the I/O switch spg^output_. 

ARGUMENTS 

sample_time 

is a decimal integer giving the time, in minutes, desired between meter display 
lines. 

CONTROL ARGUMENTS 

-halt, -ht 

terminates plotting. 

-output_file {path}, -of {path} 

directs output to a file called spg_output, or if a path is supplied, directs output 
the the file specified by path. 

-short 

compresses the width of the meter display lines (see "Notes" below). 
ACCESS REQUIRED 

This command requires access to phcs_ or metering gate . 
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NOTES 

Description of the output pattern: 

1. An initial line gives the date and time that metering sampling began. 

2. A line is given describing configuration and scheduling parameter settings. 

3. The current state of the meters since system initialization is on the next line 
where the sample time is replaced by the system initialization line. 

4. Each subsequent meter display line gives the incremental status of the meters since 
the previous line. In addition, whenever the configuration or scheduling parameter 
settings change, a notification line is interspersed. 

Description of the meter display line: 

Each line contains, in the left margin, the time that the sample was taken. Each 
sample is scheduled to be taken at an exact minute so that the amount that the time 
given exceeds the minute represents the response time. Strictly interpreted, the time 
discrepancy is the response time of a trivial request only if the metering computation 
is less than the quantum and if the command argument sample_time is greater than 
one minute so that interactive scheduling occurs. 

The remainder of the meter display line consists of a sequence of superimpositions 
over a grid 100 units wide. When the -short control argument is given, the total 
width of the grid is only 50 units, so all individual components are correspondingly 
compressed. The "Example" section below shows the output when the command is 
invoked with the -short control argument. The wider display would, of course, be 
easier to read. The 100-unit grid is created by vertical bars every 10 spaces with 
periods at the intervening midpoints between the bars. Over this grid, various metering 
quantities are superimposed in the order shown below. When the superimposition is 
complete, the resultant line containing only the last characters superimposed is printed. 

1. Time Usage Percentages 

blank 

located to the right of y to right margin user processing not in ring 0. (The 
position of y is an estimate; it is a figure that divides user processing into 
ring 0 and non-ring 0 sections.) 

blank 

located to the right of s to left of y user processing in ring 0. 

s 

time spent handling segment faults. 

P 

time spent handling page faults. 
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t 



lime spent in the traffic controller. 



interrupt processing. 

multiprogramming idle, * 

nonmultiprogramming idle. 

blank 

located from the left margin to left of *'s zero idle. 
2. Other Values 

The current average is determined from samples taken at one-second intervals 
weighted backwards in time exponentially, with a smoothing constant of 1/64. The 
effect is to average over roughly the last minute. 



q 



relative 
current 



to the left margin 

average of the ready list length. 



e 



relative 
current 



to the left margin 

average of the number of eligible processes. 



r 



relative 
current 



to the left margin 

average of the response time in seconds, for trivial requests. 



Q 



relative 
average 



to the left margin 

over a sample of quits/minute. 



S 



relative 
average 



to the left margin 

over a sample of schedulings/(10 seconds). 
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D 

relative to the right margin 

average over a sample of disk read and write traffic in units of pages/ (.1 
seconds). Full scale equals 1000/sec. 

P 

relative to the right margin 

average over a sample of all read and write traffic (bulk store and disk) in 
units of pages/ (.1 seconds). Full scale equals 1000/sec. 

V 

relative to the right margin 

average over a sample of VTOC entry read and write traffic in units of 
VTOCES/(.l seconds). Full scale equals 1000 VTOCES transferred per second. 



relative to the left margin 

number of load units at the time of the sample. If this number is greater 
than 100, 100 is assumed. 

+ 

relative to the left margin 

number of users at the time of the sample. If this number is greater than 
100, 100 is assumed. 

EXAMPLES 

The following example was generated by the command line: 
spg -short 1 

Note that the grid marks are not overwritten if the character that would appear is the 
same as both adjacent characters. (See Appendix A for a representation of the 
configuration deck used to create the system from which the metering sample was 
taken.) 
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systeni_total 



12/12/83 1247.3 mst Mon 
up= 12/10/83 OkkS.2 mst, sys_hours= 56. 0, cpu_hours= 279.8 

cpu= 5. pages* 8826, min__e= 2, max_e= 20, wsa= 0, wsf= O.5O, 
tefirst= 0.50, telast= 1.00, timax= 8.0 
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Name: system total 

SYNTAX AS A COMMAND 
system_total meter__data use_totals 
FU/VCT/ON 

inspects a daily copy of the answering service metering segment, extracts system 
availability and performance information, and places it in a month-to-date statistical 
data base. 

ARGUMENTS 

meter_data 

is the pathname of the meter data base in the form produced by as_meter_. 
use_totals 

is the pathname of the statistical data base. 
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NOTES 

This command is executed by the crank (in master.ec). The meter.data segment is a 
copy, made by the copy_as_meters command, of the segment actually being used by 
as_meter_. The use_totals segment is today.use_totals, which is subsequently used as 
input to the system_daily_report program. 



Name: test cpu 

SYNTAX AS A COMMAND 
test_cpu {-contro1_args} 

FUNCTION 

checks the CPU hardware for problems that have existed on the processors. By 
running various tests invoked by this command, you can determine whether the given 
CPU has had specific problems fixed. This command is usually used with the 
set_proc_required command if the system being tested has multiple CPUs configured. 
I If one of the test scripts fails and the successful execution of that test is dependent 
j upon installation of a particular FCO, the FCO number is displayed in the error 
I message. 

CONTROL ARGUMENTS 

-brief, -bf 

inhibits the printing of the test number and name, prior to the execution of a 
test. 

-cycle COUNT 

repeats each test for COUNT times, then proceeds on to the next test. 

-exclude LIST, -excl LIST 

excludes tests specified in the LIST, where LIST can be either a valid test number 
or a name. 

-exclude TEST.LIST, -excl TEST_LIST 

excludes the tests identified by TEST_LIST, where TEST_LIST is either a set of 
test names or numbers, from the tests that are run. 

-from TEST NUMBER/NAME, -fm TEST NUMBER/NAME 

starts testing from the test identified by TEST NUMBER or NAME. The default 
is to start testing from test 1. 

[ -help 

I displays a brief usage statement. This control argument should not be used with 
I any other control argument 
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-history_regs, -hregs 

displays history registers when a test fails. The default is not to display them. 

-long, -Ig 

displays machine conditions and history registers after a fault has occured. The | 
default is not to display them. | 

-machine_conditions, -mc 

displays machine conditions when a test fails. The default is not to display them. 

-repeat COUNT, -rpt COUNT 

repeats an entire sequence of tests for COUNT times. The default is to run the 
test set one time. 

-select TEST_LIST, -sel TEST_LIST 

executes only those tests specified by TEST_LIST, where TEST_LIST is either a 
set of test names or numbers from the tests that are run. 

The tests are described briefly below. To find out the exact details of each test, 
see the test_cpu program. The default is to run all tests. The command hne: 

test_cpu -select cmpc tinir -repeat 5 -count 2 

executes the "cmpc" 4est twice, then the "tmlr" test twice. The sequence is 
repeated five times. 

atw]J wii laiiuiw, ay^i 

Stops testing when a test failure occurs and returns to a new Multics command | 
level. The default is to continue testing with the next test. | 

-test_names 

lists valid test names and the associated test numbers known to test_cpu. This | 
control argument should not be used with any other control argument. | 

-to TEST NUMBER/NAME 

stops testing after the test identified by TEST NUMBER or NAME. The default 
is to run all tests. 

DIAGNOSTIC TESTS 

mlrstern 

checks a failure in which the fill character is placed as the first character on a 
page. This test causes a MMEl fault if the hardware fails. 

tmlr 

tries several MLR instructions, in several working combinations, across a page 
boundary. Messages are printed for any failures. 
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csl_oob 

checks a particular use of a CSL instruction where the first descriptor is 0. This 
test causes an out_of_bounds fault if the hardware fails, and a MMEl fault if it 
succeeds. 

mvn 

checks the use of an MVN instruction that moves a number to a shorter number. 
The first two characters are dropped when the hardware fails. 

mvn_ofl 

checks the use of MVN to move the number 0. An overflow indicates that the 
hardware failed. 

tct 

checks a particular TCT use. The test causes an op_not_complete if the hardware 
fails, and a MMEl fault if it succeeds. 

sreg 

checks the use of an SREG instruction that occurs as the last instruction in a 
page. The test causes an op_not_complete if the hardware fails, and a MMEl 
fault if it succeeds. 

csl_onc 

checks a particular CSL use. The test causes an op_not_complete if the hardware 
fails, and a MMEl fault if it succeeds. 

test_sc2 

checks the use of the SC modifier interacting with page faults. A MMEl fault 
occurs if the hardware fails. 

test_ci 

checks the use of the CI modifier interacting with page faults. A MMEl fault 
occurs if the hardware fails. 

rpd_test 

checks a particular use of the RPD instruction as it interacts with the hardware. 
A MMEl fault occurs if the hardware fails. 

mlr_test 

checks the use of the MLR instruction across a bounds fault boundary. The 
bounds fault is followed by a segment fault and a page fault. A MMEl fault 
occurs if the hardware fails. 

cls_test 

checks the CSL instruction across a bound fault boundary. A MMEl fault occurs 
if the hardware fails. 
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cmpc 

checks the CMPC instruction in a way that fails if a timer runout or connect 
fault occurs in midexecution when the hardware is failing. A MMEl fault occurs 
if the hardware fails. 

bad_fill 

checks the success of moving or comparing fill characters in the first two words 
of a page. Failure is indicated by a miscompare and a message to the user. 

mpy_ofl 

multiplies -2**35 by itself and checks for an overflow fault (which indicates 
failure). 

test_xed 

checks a particular indexed XED usage that fails if the first executed instruction 
is an APU-type instruction. Failure is indicated by a miscompare and a message 
to the user. 

cmpc7 

checks a CMPC failure when both strings begin seven words from a page 
boundary and run into the next page. A MMEl fault occurs if the hardware 
fails. 

extra_fill 

checks the MLR instruction to see if extra fill characters are placed after a string 
when the string crosses a page boundary. A MMEl fault occurs if the hardware 

test_cmpc_fill 

checks the fill mechanism of the CMPC instruction near a page boundary. A 
MMEl fault occurs if the hardware fails. 

acv_Testart 

checks that machine conditions can successfully be restarted after an access 
violation fault that is caused by a reference to data via an EiS (MLR) instruction. 
Failure is indicated by successive no_write_permission conditions. 

scm_tally 

checks to see if the SCM instruction works with the tally runout indicator set 
correctly. The test calls a small aim program that uses an SCM instruction. 
Because the hardware fails erratically, the test is run 10 times to get a (limited) 
statistical sampling. Failure is indicated by a message to the user indicating the 
number of times the SCM instruction failed. 
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I mvi_ascii_to_bcci 

checks nine to six (ASCII to BCD) conversion using the MVT instruction. A large 
ASCII data segment is generated. Then a BCD segment is generated using non-EIS 
conversion. Three segments are then converted from ASCII to BCD using the 
MVT instruction, and these segments are compared to the known good BCD 
segment. If any compare errors are detected, the contents of both segments are 
dumped in octal at the failing location. 

I mvt_bcd_to_ascii 

checks six to nine (BCD to ASCII) conversion using the method described for the 
mvt_nine_to_six test above. If any compare errors are detected, the contents of 
both segments are dumped in octal at the failing location. 

m vt_nine_to_f our 

checks 9-bit to 4-bit (decimal to packed decimal) conversion using the MVT 
instruction. A large segment of data, containing 9-bit characters of values 0 to 15 
in a rotating pattern, is generated. Then a second segment is generated, converting 
the 9-bit characters into 4-bit characters using non-EIS conversion techniques. 
The 9-bit data segment is then converted to three 4-bit data segments using the 
MVT instruction and compared to the known good 4-bit data. If any 
discrepancies are found, the contents of both segments are dumped in octal at the 
failing location. 

mvt_f our_to_nine 

checks 4-bit to 9-bit (packed decimal to decimal) conversion using the method 
described for the mvt_nine_to_four test above. If any compare errors are found, 
the contents of both segments are dumped in octal at the failing location. 

mvt_ascii_to_ebcdic 

checks nine to nine (ASCII to EBCDIC) character conversion using the method 
described for the mvt_nine_to_four test above. If any discrepancies are found, 
the contents of both segments are dumped at the failing location. 

mvt_ebcdic_to_ascii 

checks nine to nine (EBCDIC to ASCII) character conversion using the method 
described for the mvt_nine_to_four test above. If any discrepancies are found, 
the contents of both segments are dumped in octal at the failing location. 

ci_mod_case_2 

checks character indirect modification with two tally words and two data character 
strings, each located at a page boundary. An LDA instruction is executed on one 
tally word, CI mod, and a CMPA is executed with a second tally word, CI mod. 
Both tally words point to a character string that should be equal. If the zero 
indicator does not come on as a result of the CMPA, a MMEl fault is taken, 
indicating that the hardware failed. 

acv_restart_csl 

validates thai machine conditions can be successfully restarted after an access 
violation fault that is caused by a reference to data via an EIS (CSL) instruction. 
Failure is indicated by successive np_write__permission conditions. 
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cmpn_tst 

checks that numeric data moved with an MVN instruction can be successfully 
compared with a CMPN instruction. Failure is indicated by a MMEl fault. 

itp_mod 

checks that an EPP2,* to a word pair that contains an IT? modifier with a bit 
offset actually loads PR2 with the correct information. A MMEl fault indicates 
failure. 

mvnoosb 

checks the prepage logic of the CPU for EIS numeric instructions. Failure is 
indicated by a MMEl faulL 

cmpb_with_sixbit_of f set 

checks the CMPB instruction with a six bit offset. A MMEl fault indicates that 
the hardware failed. 

cmpb_with_rotate 

checks the CMPB instruction with a rotating pattern. A MMEl fault indicates 
that the hardware failed. 

cmpc_pgbnd 

compares a 38-character data string against a zero-length string, for a CMPC 
instruction that is located at seg 1 1767. Either an out_of_bounds condition or a 
MMEl fault indicates that the hardware failed. 

csl_pgflt 

checks that a CSL instruction does not get a no_write_perm condition if it causes 
a page fault on the target string and the source string is read-only. 

scm_pgflt 

tests a problem with the SCM instruction whereby the target operand takes a page 
fault and the resulting comparison is not made. Failure is indicated by a message 
to the user indicating the number of miscompares. 

scd_con_flt 

tests a failure with the SCD instruction that fails when interrupted by a connect 
fault. Failure is indicated by displaying the number of times the SCD failed. 

xed_dirflt_even 

tests the ability of the CPU to perform an XED, located on an even word i 
location, of a pair of instructions located on a page boundary. Failure is | 
indicated by an IPR fault. i 
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xed__dirflt_odd 

tests the ability of the CPU to perform an XED, located on an odd word 
location, of a pair of instructions located on a page boundary. Failure is 
indicated by an IPR fault. 

cmpc_adj_len 

tests the ability of the processor to perform a CMPC instruction which takes a 
fault on D2 and D2 has residue, indicated by the MIF flag. The test fails when 
the level count on D2 is not adjusted correctly on the SPL. Failure is indicated 
by an IPR fault. 

cmpc_zero_ind 

tests the ability of the processor to correctly restore the zero indicator after 
returning from a page fault on D2 after a match has occurred utilizing the 
CMPC instruction. Failure is indicated by an IPR fault 

scm_tro 

tests the ability of the processor to find the correct character using a SCM 
instruction. The tally runout indicator should not be set Failure is indicated by 
an IPR fault 

rpt_test_odd 

checks that a RPT instruction in an odd location does not fail after a page fault 
on a STZ instruction, after crossing a page boundary. Failure is indicated by an 
IPR fault. 

rpt_test_even 

checks that a RPT instruction in an even location does not fail after a page fault 
on a STZ instruction, after crossing a page boundary. Failure is indicated by an 
IPR faulL 

scd_oob_tst 

tests the conditions when D3 resides in a different segment than Dl or D2. Also 
tests the conditions if there is no match or if the scan ends a few words from 
the end of a 64K seg. A seg fault is taken on the seg described by D3. 

cmpb_onc 

checks the CPU for cmpb to complete correctly. An op_not_complete fault will 
occur on a failure. 

cmpc_a 

checks the CPU to insure that the indicators are set correctly. An illegal_opcode 
indicates an error. 

cmpc_b 

same as cmpc_a except the data and addresses are changed. 

sreg_no_write 

checks that the TRS is used (not the PSR) if a sreq instruction is executed two 
locations from a page boundary. 
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tnz 

checks for the condi tonal transfer at a page boundary. An illegal_opcode indicates 
an error. 

NOTES 

All the tests run by test_cpu are contained in the segment 
>system_library_tools>bound_cpu_tests_. This segment has an added name of cpu_tests_. 
To display the machine condition trace of a test, use the mc_trace command with the 
test_cpu command. 



Name: test_dcw 

SYNTAX AS A COMMAND 

test_dcw {device} {name} {-contro]_args} 

FUNCT/ON 

constructs and executes arbitrary DCW lists on any device supported by the I/O 
interfacer. 

ARGUMENTS 

device 

is the name of the device to be used. This can be either a specific device name, 
such as "tape_02" or "puna," or a generic device type, such as "printer" or "disk." 
If the device name is omitted, "tape" is assumed. 

name 

is the name of the tape or disk volume to be mounted. This argument is only 

used if the device is a tape or a disk, and is the name of the volume the 
operator is requested to mount. If the tape or disk volume name is omitted, 
"scratch" is assumed. 

CONTROL ARGUMENTS 

-7track, -7tr 

specifies a 7-track tape drive. This argument only applies if the device is a tape, 
-debug, -db 

runs the program in debug mode. In this mode, only the editing requests are 
recognized; no execution is allowed, and no actual device attachment takes place. 

-priv 

specifies a privileged attachment (see "Device Attachment" below.) 
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-read 

places the device in read-only mode. This control argument only applies if the 
device is a disk or a tape. 

-sys 

sets the system_flag in the rcp_ info structure during attachment (see "Device 
Attachment" below). 

DEVICE ATTACHfy/tENT 

The test_dcw command attaches the device selected using the rcp_ subroutine. 
Normally, the call is made to rcp_$attach as a nonsystem process. However, if -priv 
is used, the call is made to rcp_priv_$attach. In both cases, if -sys is used, the 
system_flag in the rcp_ info structure is set, to indicate to rcp_ that you are to be 
considered a system process. You must have re access to the rcp_sys_ gate to make 
this kind of attachment. If the device specified in the command line is a device type 
rather than a specific device, rcp_ is relied upon to select the actual device to be 
used. In either case, the name of the device actually attached is printed after 
attachment completes. 

Commands 

After the test_dcw command is invok«i, commands are read from the user_input I/O 
switch. The following commands are recognized: 

tdcw 

constructs a transfer DCW 

idcw 

constructs an instruction DCW 
nidcw 

constructs a nondata transfer IDCW 

ioip 

constructs an I/O transfer and proceed E>CW 

iotd 

constructs an I/O transfer and disconnect DCW 
iontp 

constructs an I/O transfer and proceed DCW 
odcw 

constructs a DCW from octal input 

pew 

constructs a PCW 
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opcw 

constructs a PCW from octal input 
edit, e 

selects a E>CW list to edit 

update, u 

places editor in "update" mode 

insert, i 

places editor in "insert" mode 

delete, dl, d 

deletes a DCW from the list 

print, p 

prints a DCW list 

name 

names a DCW list so that it can be referenced by name instead of number 

save 

saves all the current DCW lists in a segment 
restore 

restores DCW lists from a segment created by the save command 

execute, x 

executes a DCW list 

getstat, g 

checks for status from a previous operation 
block, b 

blocks process until an event occurs 

xs 

executes a DCW list, but leaves process blocked until special interrupt occurs 

xr 

executes a DCW list repeatedly, until some unusual status is returned 

xre 

executes a DCW list repeatedly, regardless of whether the operations succeed or 
fail 

status, St 

sets the current status reporting mode 
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rs 

reprints the status from a previous operation 
dump 

dumps data from the I/O buffer on to the terminal 
patch 

inserts data into the I/O buffer from the terminal 
pattern 

inserts data into the I/O buffer from the terminal by storing repeated copies of 
the data given 

survey 

displays data returned by a "survey devices" tape controller command 
dtstat 

displays data returned by a "read detailed status" tape handler command 

chan 

selects a specific lOM and channel for I/O 

time 

sets or prints the current time, limit for ioi timeout 
prompt 

stores a character string to be used as a prompting message 

susp 

suspends I/O on devices connected to an MPC by calling ioi_$suspend_devices 

rel 

restores I/O on devices connected to an MPC by calling ioi_$release_devices 

? 

types out the current DCW list number, current E)CW number, and the current 
editor mode 



types the word "test_dcw" to verify that the iest_dcw command is still in control 
quit, q 

releases attached device and returns 



2-506 



GB64-00 



test_dcw 



test_dcw 



no BUFFER AREA 

Once the device is attached, an I/O buffer is allocated using the ioi_ subroutine. The 
default length is 1024 words, although this can be changed later. The first 32 words 
of the buffer are reserved for DCW lists, and the second 32 words are reserved for 
the ioi_ status queue. When constructing a DCW list, care should be taken to avoid 
modifying the first 64 words (100 octal) of the buffer, or results (especially status 
reporting) may be unpredictable. 

DCW LIST PREPARATION 

The test_dcw command contains an editor that can create and update DCW lists using 
simple input statements. Up to 32 different DCW lists, each up to 32 words in 
length, can be created and selectively updated and executed. Each DCW list also has a 
PCW associated with it that, if present, is used instead of the system-supplied PCW 
when the list is executed. The 32 DCW lists are numbered from 1 to 32 in decimal. 
Each DCW list can also be given a name. The 32 DCWs in each list are numbered 
from 0 to 37 in octal. 

The DCW editor keeps track of several quantities as DCWs are entered. These are the 
current list, the current DCW number, and the current mode. When the test_dcw 
command is invoked, the current list is 1, the current DCW is 0, and the mode is 
update. 

When a DCW is entered in update mode, the new DCW replaces the current DCW in 
the current list, and the current DCW number is increased by one. 

The editor can also be placed in insert mode. In this mode, when a new DCW is 
entered, all DCWs starting with the current DCW are shifted one position down the 
list, the new DCW replaces the position formerly occupied by the old current DCW, 
and the current DCW is increased by one. DCWs shifted out of position 37 octal are 
lost. 

The edit command can be used to select a DCW list to edit, as follows: 
ed i t {list} {name} 

where: 
list 

is either the name or number of the DCW list to edit The list can also be 
specified as "*", in which case, the first available empty list is used. 

name 

is the name given to the DCW list selected by the first argument If omitted, the 
name of the list is not changed. 

This command sets the current list to the one specified, the current DCW to 0, and 
the mode to update. If the list argument is omitted, the current list is not changed, 
but the current DCW and mode are set to 0 and update respectively. 
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A DCW list can be given a name (or a new name) with the name command, 
name {name} 

where: 
name 

is the name to be placed on the current list. If omitted, the current list becomes 
unnamed. If some other list has the name specified, that list becomes unnamed. 

The mode of the editor is controlled by the insert and update commands, as follows: 

update {n} 
insert {n} 

where: 
n 

is a E>CW number, in octal. The update command puts the editor in update mode 
and sets the current DCW to n. Similarly, the insert command places the editor 
in insert mode. If n is omitted, the current DCW is not changed. 

A DCW can be deleted from the middle of the list with the delete command. 

delete {n} 

where: 
n 

is a DCW number, in octal. DCW n is deleted by moving everything after it in 
the list up one position. If n is omitted, the current DCW is deleted. The 
current DCW number is not changed. 

Any of the following commands can be used to create a DCW: 

i dew 

n i dew 

tdcw 

iotd 

iotp 

iontp 

odcw 

After a E>CW is constructed with any of these commands, it is edited into the current 
list, in the current position, according to the current mode, as described above. In all 
of the DCW commands described below, all numeric quantities are entered in octal. 
Any of the parameters shown are optional, and if omitted, the corresponding DCW 
field is zero (except for the device address field that is set to the address of the 
device assigned). 
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To create an IDCW, the command is entered as follows: 
idcw {di} {args} 

where: 
di 

is the value to be placed in the device instruction field. 

args 

are used to set the remaining fields in the IDCW and can be selected from the 
following: 

da 00 

places the value oo in the device address field, 
ci 00 

places the value oo in the channel instruction field, 
ae 00 

places the value oo in the address extension field. 

t 00 

places the value oo in the tally field. 

ec 

sets the extension control bit (ec bit). 

cont 

sets the continue bit. 
mark 

sets the marker status bit. 

A nondata transfer IDCW can be entered more easily using the nidcw command. It is 
identical in format to the idcw command, but the tally defaults to 01 and the channel 
instruction defaults to 02. 

A transfer DCW is created as follows: 
tdcw {addr} {args} 

where: 
addr 

is the value to be placed in the address field. 
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args 

are used to set the remaining bits in the TDCW and can be selected from the 
following: 

ec 

sets the extension change bit (ec). 

res 

sets the restricted bit, 

rel 

sets the relative mode bit 
lOTD, IOTP, and lONTP DCWs can be entered using the commands shown below. 

iotd {addr} {tally} {cp} 
iotp {addr} {tally} {cp} 
iontp {addr} {tally} {cp} 

where: 

addr 

is the value to be placed in the address field. 

tally 

is the value to be placed in the tally field. 

cp 

is the value to be placed in the character position field. 
Any arbitrary DCW can be entered using the odcw command. 

odcw {word} 
where: 
word 

is the octal DCW to be used. If word is omitted, an all-zero (and invalid) DCW 
is created. 

Each DCW list can have one PCW associated with it The PCW can be entered with 
the following command: 

pew {dl} {args} 

where: 

di 

is the value to be placed in the device instruction field. 
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args 

are any of the optional args listed under the idcw command, with the following 
additions: 

mask 

sets the mask bit. 

reset 

sets bits 21, 22, and 23 to form a reset PCW. 
Any arbitrary PCW can be entered with the opcw command as follows: 
opcw {word} 

where: 
word 

is the octal PCW to be used. If word is omitted, an all-zero PCW is created and 
the system-supplied PCW is used on subsequent executions of the DCW list. 

The E>CW list can be displayed at any time using the print command. 

pr i nt {1 i st} 

where: 

list 

is either the name or number of a DCW list. If list is omitted, the current list 
is displayed. If list is specified, the current list is set to that list, the current 
DCW is set to 0, and the mode is set to update. Instead of a list name, "all" 
can be used to indicate that all DCW lists are to be displayed, or "names" can be 
used to list the names of all DCW lists. 

SAVING DCW LISTS 

Once edited, a permanent copy of all the current DCW lists can be saved in a 
segment for later use by invoking the save command. 

save path 
where: 
path 

is the pathname of the segment where the data is to be saved. The segment 
always has a suffix of "test_dcw", which is supplied automatically. 



2-511 



GB64-00 



test_dcw 



tesl_dcw 



To restore the previously saved DCW lists, type: 
restore path 

where: 
path 

is the name of the segment created by the save command. If the command was 
not invoked in debug mode, all IDCWs and PCWs are updated with the device 
address of the device currently assigned. 

1(0 BUFFER EDITING 

Several commands are available to edit and display the contents of the I/O buffer. 
To enter data into the buffer, the patch command is used. 

patch offset word 1 .. .word2 .. .word i 
where: 

offset 

is the octal offset in the buffer to be patched, 
wordi 

is the value to be placed in word offset+i. 

Offsets less than 100 octal should not normally be used, as this could interfere with 
the DCW list, or the status queue. 

If a repeating pattern is desired, use the pattern command, 
pattern offset repeats word 1 .. .word2 .. .word i 

where: 

offset 

is the octal offset in the buffer where the data is to start, 
repeats 

is an octal number representing the number of times the data is to be repeated, 
wordi 

are the data words to be repeated. 
To display the contents of a buffer (in octal), use the dump command, 
dump {offset} {length} 
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where: 
offset 

is the offset in the buffer to be dumped. If omitted, 100 octal is assumed, 
length 

is the number of words to dump, in octal. If omitted, 10 octal is assumed. 

If the data consists of 8-bit bytes in binary mode (unaligned, 9 in each two words), 
the dump command can be used to dump them. The format is the same as the dump 
command, except that the data is displayed in binary, and the length is given in bytes, 
instead of words. 

If the data to be displayed is the output of a survey devices command issued to a 
tape controller, a special command can be used to display the data in a more 
meaningful way. 

survey {offset} 
where: 

offset 

is the location in the I/O buffer where the data has been stored. If the offset is 
omitted, 100 octal is assumed. 

If the data to be displayed consists of the output of a read detailed status command 
issued to a tape handler, it can be displayed with: 

dtstat {offset} 

where: 

offset 

is the location in the buffer where the status has been stored. If omitted, 100 
octal is used. 
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EXECUTING THE DCW LIST 

Once the DCW list is constructed, it can be executed as follows: 

execute {1 i st} 
where: 
list 

is the name or number of the DCW list to execute. If omitted, the current list 
is executed. If specified, the current list is changed to that list, the current DCW 
is set to 0, and the mode is set to update. The current list is copied into the 
I/O buffer starting at 0, and ioi_$connect is called to connect to relative address 
0. If the list executed has a PCW associated with it, a call is made to 
ioi_$connect_pcw instead. After the connect is made, the process becomes blocked 
until an interrupt occurs. The status of the interrupt is then printed. If the 
status indicates that the channel is still running, the process goes blocked again 
waiting for another interrupt. If the channel is not running, test_dcw is ready to 
accept another command after the status is displayed. 

If the DCW list being executed generates a terminate interrupt and a special interrupt 
(such as loading a tape drive), the following command can be useful: 

xs {list} 

This command is identical to the execute command, except that the process goes 
blocked after displaying the status from each interrupt until a special interrupt occurs. 

A DCW list can be executed repeatedly using the following command: 
xr {list} 

This command executes the DCW list specified without displaying any status until an 
error condition is detected. The final status is printed normally. 

Another variation of this can be used when it is necessary to repeat the DCW list, 
even though it has errors. 

xre {1 i St} 

executes the list specified repeatedly regardless of the status. To terminate this, it is 
necessary to quit and to use the Multics program_interrupt command, afterwards. 
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Two other commands are occasionally useful in executing a DCW list. 

block, b 
getstat, g 

The block command causes the process to go blocked waiting for an interrupt to 
occur. When it occurs, the resulting status is printed and test_dcw is ready for 
another command. The getstat command checks to see if any status is available, and 
prints it if it has occurred. The getstat command does not cause the program to go 
blocked if no status is available. 

Using the block command (or if a channel fails), it is possible to put the process in a 
state where it is waiting for an event that never occurs. If this happens, a quit 
followed by a Multics program_interrupt command can be used to return to the 
test_dcw input routine. 

STATUS REPORTING 

Status is normally reported when received by printing it on the terminal. Status can 
be reported in three modes, as follows: 

brief, bf 

is the default mode. The status message consists of the interrupt level in decimal, 
two words of lOM status in octal, and the major and minor status fields in 
binary. 

long, Ig 

consists of all eight words of the ioi_ status queue entry, in octal, 
edited, ed 

is an English-language interpretation of the status. 
The status mode is initially set to brief, but this can be changed as follows: 
status {mode} 

where: 
mode 

is one of the three status modes described above. If omitted, the current mode is 
printed. 

The previous status can also be redisplayed using the reprint status command, 
rs {mode} 

where: 
mode 

is one of the three modes described above. If omitted, edited mode is assumed. 
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OTHER COMMANDS 

Several other commands exist that can be useful. To set the length of the ioi_ 
timeout interval, use the time command. 

time {n} 

where: 

n 

is the time limit in decimal seconds. If n is omitted, the command prints the 
current limit. 

To change the size of the I/O buffer, type: 
work {n} 

where: 
n 

is the buffer length desired in decimal words. If n is omitted, the work 
command displays the current buffer length. 

To select a specific lOM and channel for I/O, the chan command can be used. 
Chan {iom} {channel} 

where: 
channel 

is the IOM channel, in octal. 

iom 

is the IOM selected. 

If channel is specified, but IOM is omitted, the IOM is assumed to be 1. If both are 
omitted, both are set to 0, indicating that ioi_ should make its own selection. The 
test_dcw command must be invoked with the -priv control argument in order to use 
this feature. 
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To suspend I/O on devices to connect to an MPC, use: 

SUSP 

To restore I/O, use: 
rel 

These commands call the appropriate ioi_ entry points to accomplish their task. They 
are valid anly if test_dcw was invoked with the -priv control argument and the device 
is connected to an MPC. 

To read the special device status stored by the previous operation, use: 

get_speci al__status 
To read the detailed device status stored by the previous operation, use: 

get_detai l_status 

If a prompt message is desired when tesi_dcw is ready for input, you can supply one 
as follows: 

prompt {chars} 

where: 

chars 

is the data to be used for prompting. If chars is omitted, no prompt message is 
used. 

To exit from the test_dcw command, type: 
quit, q 

The I/O device currently attached is detached, and the program terminates. 
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Name: test fnp 

SYNTAX AS A COMMAND 
test_fnp fnp_tag {-control_args} 
FUNCT/ON 

tests FNPs with the CSD-supplied FNP test programs. 

ARGUMENTS 

fnp_tag 

is the tag of the FNP to be tested. This FNP must have been shut down or 
dumped; it cannot be involved in testing by another process. Level 6 FNPs cannot 
be tested with this command. 

CONTROL ARGUMENTS 

-exec name 

specifies the FNP executive to be run initially. The name can be either "BOS" or 
"lOS." The default is BOS. ( Note: BOS here does not refer to the Bootload 
Operating System.) 

-input_switch name, -isw name 

specifies the I/O switch from which operator input is read. The default switch is 
user_input. 

-message_switch name, -msw name 

specifies the I/O switch to which messages intended for the T&D line printer are 
written. The default switch is user_outpuL The FNP T&D programs generate 
output of this form if their query "IS A PRINTER AVAILABLE?" is answered 
affirmatively. 

-output_switch name, -osw name 

specifies the I/O switch to which messages intended for the bootload console are 
written. The default switch is user_output. 

NOTES 

The FNP type of the FNP selected for testing is obtained from information contained 
in the Channel Definition Table (>system_control_l>cdt). If the user does not have 
access to this data base, the following query is issued: 

test_fnp: What is the FNP type of FNP fnp_tag? 
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If the user hits RETURN, he is prompted with the following: | 
Answer DN66OO, DN667O, DN355, or quit. 

If the "quit" response in entered, control is returned to the current command 
processor. 

Users should be familiar with the CSD offline version of TST3BT. The test options, | 
queries, and message diagnostics relevant to FNP testing are produced by the FNP test 
programs themselves. The documentation for the offline version of TST3BT running 
under the PAS2 EXEC, and the T&D documentation for the FNP tests, contain 
information on actual dialogue with this program; it is the same as the dialogue with 
the offline version. 

The bootload console of TST3BT is simulated by the Multics terminal controlling the | 
process running test_fnp. By default, test output appears on the terminal, and 
responses are expected from the terminal. Normal Multics input line editing applies to 
all responses, and lowercase input is acceptable. 

The response "quit" to any query of test_fnp, regardless of how it was generated, 
terminates the test session, releases the FNP, and returns to command level. 

The REQUEST button of the bootload console is simulated by striking the QUIT key j 
and using the program_interrupt (pi) command, to return to test_fnp. Normally, the 
REQUEST button causes an interrupt to be sent to the FNP directing the FNP 
executive to enter its request loop. 

Access to the tandd_ gate is required. Access to >scl>cdt is required to obtain the 
correct model number of the FNP. If you do not have access to the CDT, the 
default model number is DN6670. (This is the only FNP currently supported.) 1 

The tests executed by test_fnp are sorted in the keyed sequential vfile_ 
>system_library_tandd>tandd_deck_file. These tests are loaded from the CSD-distributed 1 
"FNP binary deck tapes" by the load_tandd_library command (described in the 
Multics Online Test and Diagnostics Reference Manual, Order No. AU77). 



Name: test io ^daemon 

SYNTAX AS A COMMAND 

test_i o_daemon pathname 
or 

test_io_daenion -control_arg 
FUNCTION 

runs the I/O daemon subsystem in test mode in the user's process. 
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ARGUMENTS 
pathname 

is the pathname of an iod_tables segment produced by the iod_tables_compiler 
command. The directory containing the iod_tables segment is used as the lest 

directory. 

CONTROL ARGUMENTS 

-directory dir_pathname, -dr dir_pathname 

specifies the pathname of a test directory. The iod_tables segment contained in 
the directory is used as the test iod_tables segment. 

NOTES 

For more details on the use of this command, refer to the System Maintenance 
Procedures manual, Order No. AM81. 

LIST OF REOUESTS 

coord 

allows the coordinator part of your test process to come to command level. If 
you want to run just a coordinator, this request is the only one you have to 
issue. If you want to run both a coordinator and a driver, you have to follow 
this request with the driver request. 

debug 

calls the system debug command to allow you to set and reset break points and 
execute interactive Multics commands (by using the debug request). You may 
issue the debug request from both coordinator command level and driver 
command level. The system response to this request is "Calling debug." 

driver 

allows the driver part of your test process to come to command level. If you 
want to run just a driver, this request is the only one you have to issue. If you 
want to run both a coordinator and a driver, you have to preceed this request 
with the coord request. Note: the driver request is not accepted by the 
coordinator part of your test process if you've suspended the driver part 
previously by using the coord request 

pi 

generates a program_interrupt signal. This request allows you to discard any 
undesirable output (or occurence) by generating a quit signal, and to then return 
to the last stack frame with a program_interrupt handler (i.e., debug or probe). 
Normally, you use this request to return to the debug or probe request after 
you've interrupted one of its functions with a quit signal. You may issue this 
request from both coordinator command level and driver command level. 
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probe 

calls the system probe command to allow you to set and reset break points and 
execute interactive Multics commands (by using the probe request). You may 
issue the probe request from both coordinator command level and driver command 
level. The system response to this command is "Calling probe." 

resume 

directs the driver to attempt recovery from iodd signal command level (in test 
mode, the driver will not attempt recovery of error conditions, but instead, after 
all error messages are displayed, will stop at iodd signal command level) or to 
return to normal command level from request command level or to quit command 
level (aborting any current request), as if it were not in test mode. You may 
only issue this request at driver command level. 

return 

does the same thing as the logout command, except that it doesn't display any 
messages. You may issue this request from both coordinator command level and 
driver command level. When you issue it from driver command level, your 
process returns to coordinator command level (assuming you were running both a 
driver and a coordinator). The coordinator is not notified that the driver has 
logged out. When you issue the return request from coordinator command level, 
the entire coordinator /driver test environment is released and your process returns 
to the original process command level. 

EXAMPLES 

First, type either: 

tes t_i o_daemon >udd>Sysrta i nt>Marg i e> i od>new_tab 1 es 

or: 

test_i o_daemon -dir >udd>SysMa i nt>Marg i e>i od 

The system will respond with: 

Enter command: coordinator, driver, or return: 
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I 
I 



I 

I 



I 
I 



! 



this point, you have four choices: 

If you want to run both a coordinator and a driver, proceed as follows: 

! coord 

I/O Coordinator Version: x.x 
I/O Coordinator initialized 

! driver 

I/O Daemon Driver Version: x.x 

Driver running in test mode. 

Enter command or device/request type: 

To exit from test mode in this case, type "return" or "logout" twice. 

If you want to run just a coordinator, proceed as follows: 

! coord 

I/O Coordinator Version: x.x 
I/O Coordinator initialized 

To exit from test mode in this case, type "return" or "logout" once. 

If you want to run just a driver, proceed as follows: 

! driver 

I/O Daemon Driver Version: x.x 

Driver running in test mode. 

Enter command or device/request type: 

To exit from test mode in this case, type "return" or "logout" once. 
If you want to return to Multics, type "return." 
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Name: test tape 

SYNTAX AS A COMMAND 
test_tape {-control_args} 
FUNCTION 

tests a tape drive or tape reel. 

CONTROL ARGUMENTS 

-comment STR, -com STR 

allows you to pass additional information about the requested volume mount to 
the operator. 

-compare STR, -comp STR 

writes and then reads a tape on device STRl, and then automatically has the 
operator mount the tape on device STR2 and read the tape. The mounting and 
reading continues to device STRn. At least two devices must be specified. Only 
one device is attached at a time. The full device name (e.g., -comp tapa_05 
tapa_07) must be used. This control argument cannot be used with -device. 

-count N, -ct N 

indicates the number of records to be written or read, where N is a decimal 
integer. Each write operation creates one 1040 word physical record. If this 
control argument is not given, then the entire tape is written or read. 

-density N, -den N 

indicates the tape density, where N can be either 6250, 1600, or 800. The default 
is 1600. 

-device STR, -dv STR 

selects a specific tape unit; STR must be the complete device name. If this 
control argum.ent is not given, the system finds a free tape unit (e.g., -device 
tapb_08). It is incompatible with -compare. 

-no_data_compare, -ndc 

disables comparison of the data read to a known pattern. This control argument 
is useful for verifying that a tape can be read without knowing what data is on 
the tape. 

-pattern N, -ptrn N 

specifies N as the word of octal data to fill the data buffers, where N can be a 
maximum of 12 octal digits. If fewer than 12 digits are given, the field is 
padded on the left with zeroes. If this control argument is not given, a pattern 
of 222222222222 is used. The -pattern control argument cannot be used with 
-random. 
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-random 

fills the data buffers with a known random data pattern. It cannot be used with 
-pattern. 

-raw 

displays raw hex detailed status with each error message in addition to an 
interpreted display. 

-read, -r 

identifies the mode of the test. The tape is mounted without a write ring and 
the read-only pass is performed. 

-track?, -tk7 

specifies a 7-track tape drive as the test unit The default is 9 track. 

-volume ID, -vol ID 

specifies a tape by its volume identification number, which can have a maximum 
of nine characters. If -volume is not given, a default of "test_tape" is used. 

-wait N, -wt N 

attempts to attach the device N times, after one-minute waits, if the device 
desired is being used by another process. If after N waits the device still cannot 
be attached, the program bypasses the device. The default for N is two times. 

-write, -w 

identifies the mode of the test. The tape is written and the read pass is 
bypassed. 

-write_read, -wr 

identifies the mode of the test. The tape is written and the read pass is 
performed. This is the default. 

NOTES 

The test_tape command senses the End of Tape Mark (EOT) and stops even if the 
record count has not been exhausted. Typing test_tape with no control arguments has 
the same effect as: 

test_tape -vol test-tape -den I6OO -ct 100000 -ptrn 222222222222 -wr 
Listed below is a summary of the default control argument values. 
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-vol ume 
-comment 
-devi ce 



(test-tape) 
(NONE) 

(one previously 



count 
ndc 



(100000{ent i re tape}) 
(OFF) 



assigned, or a 
free device) 



random 
pattern 
wr 1 te 
read 



(OFF) 

(222222222222) 



-compare 
-dens i ty 
-track 
-wa i t 



(OFF) 
(1600) 

(9) 
(OFF) 



raw 



(ON) 
(ON) 
(OFF) 



Name: total time meters, ttm 

SYNTAX AS A COMMAND 
ttm {-control_arg} 
FUNCTION 

prints out the CPU time percentage and average CPU time spent doing various tasks. 

CONTROL ARGUMENTS 

-report_reset, -rr 

generates a full report and then performs the reset operation. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 

the last call with -reset specified. If -reset has never been given in a process, it 

is equivalent to having been specified at system initialization time. 

ACCESS REQUIRED 

This command requires access to phcs_ or metering gate_. 



If the total_time_meters command is given with no control argument, it prints a full 
report 



NOTES 
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The following are brief descriptions of each of the variables printed out by 
total_time_meters. Average CPU times are given in microseconds. In the description 
below, system CPU time is the total amount of CPU time generated by all configured 
CPUs. Idle time is CPU time consumed by an idle process; an idle process is given a 
CPU only if no other (nonidle) process can be given that CPU. System nonidle time 
is the difference between system CPU time and the aggregate idle time. In this 
computation, MP idle time, work class idle time, and loading idle time are considered 
as overhead time and are included in system nonidle time. That is, system idle time is 
defined to include only the idle time caused by light load; it does not include the idle 
time caused by system bottlenecks; that time is counted as overhead. 

The three columns in the display contain, respectively, the percent of system CPU 
time, percent of system nonidle time, and average time per instance (for the overhead 
tasks). The percents of non-idle time are included to assist the user in comparing 
values measured under light load with those measured under heavy load. It can not be 
emphasized too often that measurements made under light load should not be used to 
make tuning or configuration decision. 

Several of the overhead task names are indented, to indicate that they are part of the 
preceding, non-indented task. The percents for these indented tasks are also included 
in the percent for the preceding task. That is, in the example at the end of this 
description, page faults used 1.49% of system CPU time; 0.14% was used by PC Loop 
Locks, and the remaining 1.35% was used by other page fault overhead. 

Page Faults 

is the percentage of CPU time spent handling page faults and the average time 
spent per page fault. 

PC Loop Locks 

is the percentage of CPU time spent looping on the page table lock, and the 
average time spent per looplocking. This number will be nonzero only on a 
multiprocessor system. This number is also included in page fault time. 

PC Queue 

is the percentage of CPU time spent processing the core queue, and the average 
time spent per core queue processing. The core queue is used to prevent loop 
looks in page control on interrupt side. If an interrupt for a page I/O is 
received when the page table is locked, an entry is made into the core queue. 
When the page table is next unlocked, the core queue is processed. 

Seg Faults 

is the percentage of CPU time spent handling segment faults, and the average 
time spent per segment fault These values do not include the time spent handling 
page faults that occurred during the segment fault handling. 

Bound Faults 

is the percentage of CPU time spent handling bound faults and the average time 
spent per bound fault These values do not include time spent handling page 
faults that occurred during bound fault processing. 
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Interrupts 

is the percentage of CPU time spent handling interrupts, and the average time 
spent per interrupt. 

Other Fault 

is the percentage of CPU time spent handling certain other faults. The fault 
processing time included is fault handling time that is not charged to the user 
process as virtual CPU time and that does not appear elsewhere in the 
total_time_meters output (i.e., it is not page fault, segment fault, or bound fault 
processing). The vast majority of the time included as Other Fault processing is 
related to the processing of connect faults and timer_runout faults. 

Getwork 

is the percentage of CPU time spent in the getwork function of traffic control, 
and the average time spent per pass through getwork. The getwork routine is used 
to select a process to run on a CPU and to switch address spaces to that process. 
This number is also included in other fault time. 

TC Lx)op Locks 

is the percentage of CPU time spent looping on a traffic control lock, and the 
average time spent per looplocking. The locks included in this category are the 
global traffic control lock and the individual Active Process Table Entry (APTE) 
locks. This time is nonzero only on a multiprocessor system. This number is also 
included in other fault time. 

Post Purging 

is the percentage of CPU time spent in post purging processes that have lost 
eligibility, and the average time spent per post purge. Post purging a process 
involves moving all of its per-process pages that are in main memory into the 
"most recently used" position in the core map and computing the working set of 
the process. This time is nonzero only if the "post_purge" tuning parameter is set 
to "on." This number is also included in other fault time. 

MP Idle 

is the multiprogramming idle. This is the percentage of CPU time that is spent 
idling when processes are contending for eligibility, but not all contending 
processes are eligible. This occurs because some site-defined or system limit on 
eligibility has been reached — e.g., maximum number of eligible processes (tuning 
parameter "max_eligible"), maximum number of ring 0 stacks (tuning parameter 
"max_max_eligible"), per-work-class maximum number of eligible processes, working 
set limit, etc. MP idle is CPU time wasted in idling because the eligibility limits 
are set too low for the configuration, or because there is not enough memory in 
the configuration to hold the working sets of a larger number of eligible 
processes. 
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Work Class Idle 

is the percent of CPU time spent idling because the only processes that could 
have been run belonged to work classes that had used their maximum percentage 
of CPU time. Setting upper limits on work classes will cause the system to go 
idle rather than run processes in those work classes that have reached their 
maximilm percent. This meter indicates the percent of CPU time wasted in idling 
because of the setting of these limits. 

Loading Idle 

is the percentage of CPU time that is spent idling when processes are contending 
for eligibility, not all contending processes can be made eligible, and some eligible 
processes are being loaded. Being loaded means wiring the two per-process pages 
that must be in main memory in order for a process to run — the first page of 
the descriptor segment (DSEG) and the first page of the process descriptor 
segment (PDS). 

NMP Idle 

Is the nonmultiprogramming idle — the percentage of system CPU time that is 
spent idling when all processes contending for eligibility are eligible. Time is 
charged to NMP idle under two different circumstances: 1) there are fewer 
processes contending for eligibility than there are processors in the configuration; 
2) there are fewer non-waiting processes than there are processors in the 
configuration (that is, most of the eligible processes are waiting for system events 
such as page faults), and no additional processes are contending for eligibility. 
Both of these circumstances are caused by light load; therefore NMP idle time, 
along with zero idle time, is subtracted from system CPU time to get system 
non-idle time. 

Zero Idle 

is the percentage of system CPU time that is spent idling when no processes are 
ready and contending for eligibility. 

Other Overhead 

is the percentage of system CPU time that is overhead but cannot be attributed 
to any of the above categories of overhead. This is almost entirely instrumentation 
artifact, due to a small but indeterminable amount of time between the occurrence 
of a fault or interrupt and the reading of the system clock (which begins the 
charging of time to some overhead function). Due to hardware features such as 
cache memory and associative memory, this time is not constant per fault, even 
though the same instruction sequence is executed each time. Other Overhead 
represents the effect of this nondeterminism. 

Virtual CPU Time 

is the precent of CPU time delivered to user processes as virtual CPU time. 
Virtual CPU time is time spent running user ring code (commands, application 
programs, etc.) or inner ring code in direct response to user ring requests (via 
gate calls). System virtual CPU time is total system CPU time less all system 
overhead and idle time. It is the sum of the virtual CPU time charged to all 
processes. One objective of tuning is to maximize virtual CPU lime. 
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EXAMPLES 

The following is an example of the information printed when the total_time_meters 
command is invoked with no control argument. 

Total metering time 91:33:53 
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Name: traffic control meters, tcm 

SYNTAX AS A COMMAND 
tcm {-control_args} 
FUNCTION 

prints out the values of various traffic control meters. 
CONTROL ARGUMENTS 
-counters, -ct 

prints out the number and frequency of certain paths through the traffic 
controller. 

-gen 

prints out general traffic control information. 
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-queue, -qu 

prints out certain resource usage as a function of depth in the eligible queue. 

-report_reset, -rr 

generates a full report and then performs the reset operation. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 
the last call with -reset specified. If -reset has never been given in a process, it 
is equivalent to having been specified at system initialization time. 

ACCESS REQUIRED 

This command requires access to phcs_ or metering gate , . 
NOTES 

If the traffic_control_meters command is given v^^ith no control arguments, it prints a 
full report 

The following meters reflect activity of the traffic controller, and some constants used 
therein. They are printed if the -gen control argument is specified. 

A.ve queue length 

is the average number of processes in the eligible and priority queues. This is the 
average number of ready, waiting, or running proce^es. 

Ave eligible 

is a recent average of the number of eligible processes. 
Response time 

is the average time between a process' receiving an interactive wakeup and the 
awarding of eligibility to the process. The response time seen by the user is 
larger than this meter. 

The following meters pertain to the number and frequency of certain paths through 
the traffic controller. They are printed if the -ct control argument is specified. 

Interactions 

is a count of, and the average time between, terminal interactions. 
Loadings 

is a count of, the average time between, and the number per interaction of 
process loadings. 

Blocks 

is a count of, and the average time between, calls to "block" to block some 
process. 
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Pauses I 

is a count of the number of times processes were delayed in ring 0. These pauses | 

are due to suspected covert channel activity. Refer to "Segment State Change" | 

under the output of the file_systeni_meters command. | 

Wakeups 

is a count of, and the average time between, wakeup signals being sent. 
Schedulings 

is a count of, the average time between, and the number per interaction of trips 
through the scheduler /rescheduler function that caused priorities to be changed. 

Lost priority 

is the number of times the alarm clock went off indicating a priority process that 
had been running lost its eligibility because it had used up its eligible time; i.e., 
its eligible time exceeded the CPU quantum that the process remains in the queue. 
The process reenters the traffic controller to be rescheduled. 

Priority boosts 

is the number of times the alarm clock went off indicating a priority scheduling 
process on the ready list should be granted high priority; i.e., have its waiting 
time before rescheduling set to 0. The process is then resorted into the ready list 
with its new, higher priority. 

Wait Page 

is a count of, the average time between, and the number per interaction of calls 
to force some process to a wait state in order to wait for page transfer. 

Wait PTL 

is a count of, the average time between, and the number per interaction of calls 
to force some process to a wait state in order to wait for the page table lock. 

Wait Other 

is a count of, the average time between, and the number per interaction of calls 
to force some process to a wait state in order to wait for events other than page 
control events. 

Total Waits 

is a count of, the average time between, and the number per interaction of calls 
to force some process to a wait state. 

Notify Page 

is the number of, and average time between, calls to notify processes waiting for 
page transfer events. 

Notify PTL 

is the number of, and average time between, calls to notify processes waiting for 
page table unlockings. 
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Notify Other 

is the number of, and average time between, calls to notify processes waiting for 
all other events. 

Total Notifies 

is the' number of, and the average time between, notify calls (i.e., returning a 
waiting process to the ready state). 

Get Processor 

is the number of, and average time between, calls to get_processor. Get_processor 
is called at notify time to find a CPU on which to run the notified process. An 
idle process or lower priority running process is preempted. 

Pre-empts 

is a count of, average time between, and the number per interaction of process 
preemptions and timer runout faults. 

Getwork 

is the number of, and average time between, calls to getwork. Getwork is the 
dispatcher portion of the scheduler; it finds a process to run on the executing 
CPU. 

Retry getwork 

is the number of, and average time between, retries of the getwork function. 
Extra notifies 

is the number of, and average time between, notify calls that found no process 
waiting on the notified event. 

Last EN event 

is the last notified event for which no process was waiting. 
Notify timeout 

is the number of times a notify was not received by a waiting process within 
notify_timeout_interval (a tuning parameter). This is printed only if the count is 
nonzero. 

Last NTO event 

is the last event on which a notify timeout occurred. 

The following meters pertain to the eligible queue. They are printed if the -qu 
control argument is specified. 

Depth 

is the depth of the process within the eligible queue. A process deep in the 
eligible queue is run only if processes above it cannot run. 

%PF 

is the percentage of page faults that occurred from processes at this depth. 
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TBPF 

is the average time between page faults at this depth. 
%GTW 

is the percentage of getwork calls being made when a member of this priority 
relinquishes control. 

TBS 

is the average time between getwork calls at this priority level. 
%CPU 

is the percentage of CPU time consumed by members of this priority. 
EXAMPLES 

The following is an example of the information printed when the traffic_control_meters 
command is invoked with no control arguments. (See Appendix A for a representation 
of the configuration deck used to create the system from which the metering samples 
were taken.) 
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Getwork 
Retry getwork 
Extra notifies 
Last EN event 

DEPTH %PF 

1 10. if 

2 10.7 

3 10.3 
k S,k 

5 8.9 

6 8.3 

7 7.6 

8 3^.2 
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Name: traffic control queue, tcq 

SYNTAX AS A COMMAND 
tcq {-control_arg} 
FUNCT/ON 

prints out the state of the traffic control queue at the time of the call. 
CONTROL ARGUMENTS 
-all 

print information about all processes. The default is to print information only for 
processes in ready queues. 

ACCESS REQUIRED 

This command requires access to phcs_ or metering, gate , . 
NOTES 

The following items are printed out by the traffic_control_queue command, 
avq 

is the average number of processes in the eligible and priority queues. This is the 
average number of ready, waiting, or running processes. 
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elapsed time 

is the time since lraffic_control_queue was last called. This equals 0 if it is the 
first time the program was called for the given process. 

active last 15 sec. 

is the number of processes that changed state during the last 15 seconds. 

The following items are printed out for each user presently in the ready queue. 

flags 

are one-bit indicators in the active process table (APT) entry for the user. 
The following flags are printed: 
E process is eligible 

W Interprocess Communication (IPC) wakeup pending 

S stop pending 

P process being preempted 

L process is loaded 

D process has descriptor base register loaded 
H process is a hardcore process 
I process is an idle process 

The flags are preceded by a letter indicating the state of the process. The allowed 
states are: 

e empty or unused 

X running 

r ready 

w waiting 

b blocked 

s stopped 

p waiting for page table lock 

If the flag is followed by a parenthesized letter, the letter is the CPU tag of the 
processor on which that process must be run. 

dtu 

is the incremental CPU time (in seconds) the process has used since the tcq 
command was last called. 

dpf 

is the incremental number of page faults the process has taken since the tcq 
command was last called. 

temax 

is the value (in milliseconds) of temax of the process. Temax is the maximum 
amount of CPU time the process may use in the current eligibility quantum. 
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te 

is the value (in milliseconds) of te of the process. Te is the amount of CPU 
time used in the current eligibility quantum. 

ts 

is the ^'alue (in milliseconds) of ts of the process. Ts is the amount of CPU time 
used since scheduling priority changed. 

ti 

is the value (in milliseconds) of ti of the process. Ti is the amount of CPU time 
used since the process interacted, or the tuning parameter timax, whichever is less. 

tssc 

is the real time (in seconds) since the state change of the process. 

event 

is the event for which the process is waiting. If this value is 0, the process is 
not waiting. 

d 

is the device identifier of the device containing the page, if the process is waiting 
for a page. This is not currently used. 

ws 

is the modified value of the working set estimate being used for the process. 

wc 

is the number of the work class to which the process belongs, 
process 

is the name of the user who owns the process, 
workclass credits 

is the value (in milliseconds) of CPU time used by the workclass. 
EXAMPLES 

The following is an example of the information printed when the traffic_control_queue 
command is invoked with no control argument. (The last column, containing the 
Person_ids representing the process flag, has been omitted due to space limitations.) 
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Name: tty dump 

SYNTAX AS A COMMAND 

tty_dump channe1_name {-contro1_args} 

FUNCTION 

displays on the user's terminal the contents of the ring zero data bases describing 
either the current state of selected communications channels managed by the Multics 
Communication System or the state of such channels at the time of a system crash. 

ARGUMENTS 

channeLname 

specifies the communications channels for which the state is to be displayed. The 
star convention is allowed (e.g., b.h202.**). This argument is incompatible with the 
-user control argument. 

CONTROL ARGUMENTS 

-ascii 

specifies that the contents of buffers are to be interpreted as ASCII characters in 
addition to being displayed as octal or hexadecimal values. 

-all, -a 

specifies that, for each channel selected by the above arguments, information is to 
be displayed from the data bases of the channel, its parent multiplexer, its 
grandparent multiplexer, etc., up to the top level multiplexer channel. For 
example, for b.h202.prtl, all information from the data bases of b.h202.prtl, 
b.h202, and b that is related to b.h202.prtl would be displayed. 

-brief, bf 

suppresses display of the buffer contents. Only the addresses, size, and flags for 
each buffer are displayed. 

-ebcdicS 

specifies that the contents of buffers are to be interpreted as EBCDIC (8-bit 
byte) characters in addition to being displayed as octal or hexadecimal values. 

-ebcdic9 

specifies that the contents of buffers are to be interpreted as EBCDIC (9-bit 
byte) characters, in addition to being displayed as octal or hexadecimal values. 

-erf N 

specifies that information about the channels is to be taken from the system 
dump associated with error report form (ERF) N located in the dumps search list. 
If this control argument is omitted, information about the currently running 
system is displayed. This control argument is incompatible with the -user control 
argument 
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-hex8 

specifies that the contents of buffers are to be displayed as hexadecimal values, in 

addition to any character interpretation. Each 8-bit byte in a word is displayed 
(nine hexadecimal digits). 

-hex9 

specifies that the contents of buffers are to be displayed as hexadecimal values, in 
addition to any character interpretation. The low order 8 bits of each 9-bit byte 
in a word is displayed as two hexadecimal digits. 

-Icte 

specifies that the logical channel table entries (LTE) for the selected channels are 
to be displayed in addition to the other information normally displayed. If -all is 
specified, the LCTEs of all parent multiplexers are also displayed. 

-long, -Ig 

specifies that the contents of any input and output buffers for the channels are 
to be displayed. This is the default. 

-octal 

specifies that the contents of buffers are to be displayed as octal values in 
addition to any character interpretation. Octal is the default numeric mode for 
buffer contents display. 

-subchan, -sbc 

specifies that information from the data base of the parent multiplexer related 
-user STR 

specifies that the state of all communications channels attached by the specified 
user(s) is to be displayed. STR is a starname used to identify the users and is 
matched against the Person_id.Project_id of each logged in user. For example, 
"*Smith.M*" would match any user whose Person_id ends with "Smith" that is 
logged in on a project that starts with "M". This control argument is 
incompatible with the channel_name argument and the -erf control argument 

ACCESS REQUIRED 

Use of the tty_dump command without the -erf control argument requires access to 
the gate phcs_. 

NOTES 

The description of the dump_segment command in the Multics Commands and 
Active Functions manual. Order No. AG92, provides detailed information on the 
various buffer display formats. 

The default mode for buffer displays is to display their contents as octal values 
without any character interpretation. 
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There are two sets of conflicting control arguments in tty_dump: three with which to 
specify the base of numeric display (-octal, -hex8, and -hex9), and three with which 
to specify character code interpretation (-ascii, -ebcdic8, and -ebcdic9). If conflicting 
control arguments are given on the command line, the last one specified will be used. 

EXAMPLES 

The command line: 

tty_dump b.h202.*»'< -all 

displays the state of multiplexer b.h202 and its subchannels. Displayed information 
includes the WTCBs/TCBs of the subchannels, multiplexer-specific data for the 
subchannels, global data for the multiplexer, and the PCB of the multiplexer's physical 
FNP channel. 

By comparison, the command line: 

tty_dump b.h202 -al 1 
displays only global multiplexer data and the PCB. 



Name: tty lines 

SYNTAX AS A COMMAND 
tty_l i nes {arg} 
FUNCTION 

prints information about communications channels defined in the channel definition 
table (CDT). An optional argument can be used to print information about a subset 
of channels. 

ARGUMENTS 

id STR 

prints information about channels on which the terminal most recently dialed up 
has an identification code specified by STR. The string STR is four characters 
long. 

dlN 

prints information about each channel that has been dialed up N times or more. 
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d=N 

prints information about each channel that has been dialed up exactly N times. 

stN 

prints information about each channel whose current state code is N (see "Notes" 
below). 

acN 

prints information about each channel whose activity code is N (see "Notes" 
below), 

slN 

prints information about the Nth entry in the CDT. 
-type STR 

prints information about each channel on which the most recently dialed terminal 
was of the terminal type specified by STR. 

NOTES 

If the tty_lines command is given with no argument, it prints information about all 
channels in the CDT. For each channel, a line is printed in the following format: 

NAME TYPE D S W A BAUD Person_id Project_id (I D) C 



is the channel name, e.g., a. 1006. 
TYPE 

is the terminal type that has most recently dialed the channel, or NU if the 
channel has not been used. 

D 

is the number of times the channel has been dialed up. 

S 

is the current state of the channel. It may have one of the following values: 

1 hung up 

2 listening (ready for dialup) 
5 d i a 1 ed 



W 

is an internal variable indicating what the answering service expects to happen 
next to the channel. 
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A 

is the activity code for the channel. It may have one of the following values: 

1 hung up 

2 listening (ready for dialup) 

3 dialed up but not logged in 

k user is logged in but process not yet created 

5 user process has channel 

6 auto_cal 1 line is in process of dialing out 

7 auto__call line is in use (dial complete) 



BAUD 

is the baud rate of the channel 
Person_id 

is the Person_id of the current user of the channel. If A is not 4 or 5, this 
field is omitted. 

Project_id 

is the Project_id of the current user of the channel. If A is not 4 or 5, this 
field is omitted. 

ID 

is the identification of the terminal currently using the channel. If S is not 5, 
this field is omitted. 

C 

is the comment field from the CDT entry. 

I 

I Name: tune ^disk 

I SYNTAX AS A COMMAND 

tune_disk DRIVE_NAME IO_TYPE -load N -response N 
or 

tune_disk reset__max 
or 

tune_disk reset__sys 
or 

tune disk stagnate N 
or 

tune_disk system IO_TYPE {-max n} {-map IO_TYPE} 
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FUNCTION 

alters disk tuning parameters. A description of disk tuning techniques can be found in 
the Multics System Maintenance Procedures manual, Order No. AM81. 

ARGUMENTS 

DRIVE_NAME 

is the name of the disk drive to be tuned. (For example dska_05). 
IO_TYPE 

identifies one of the I/O types tunable by tune_disk, where IO_TYPE can be one 
of the following: 

page_read 
page_wr i te 
vtoce_read 
vtoce_wr i te 
test_read 
test wr i te 



reset_max 

requests that all queue maximum depth meters be reset in the disk_seg database. 
The time and date at which the meters were last reset is also maintained in the 
database. This argument is useful to permit a new/lower max depth to be seen 
after altering tuning parameters, or after an Allocation Lock has occurred. 

reset_sys 

requests that all system depth counters be reset to 0. This is useful after altering 
system depth counter mapping. If counter mapping has been changed while 
requests were in the queue, the counter which had been used may be left 
artificially high. Resetting back to 0 lets the system correct the value. 

stagnate N 

specifies a change of the system wide stagnation time period to the specified 
number of seconds. Tune_disk sets a maximum stagnation time period of 6 
minutes. 

system 

indicates modification of a system-wide optimization f actor = The maximum depth 
and /or mapping for the specified io_type will be latered. If neither a maximum 
depth value, nor a mapping is altered an error message is issued. 
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1 CONTROL ARGUMENTS 

I -load N, -Id N 

I defines the optimization maximum queue loadpoint for the specified drive. The 

I value N is stated in terms of queue elements. For blocking I/O, this value would 

I typically reflect a point which preserves sufficient multiprogramming. For 

I non-blocking I/O, this would typically reflect a point before resource saturation 

j would occur and cause the I/O type to become blocking. The -load value is one 

I of the two points (along with -response) that define the optimization line. If 

I -load 1 is specified, the initial response value is the optimizing multiplier and no 

I load optimization is performed. 

I -map lO.TYPE 

I specifies that the current depth counting for the specified system-wide optimization 

I entry should be done using the counter for io_type. For example: 

I tune_disk system PageRead -map PageWr i te 

I Would have the depth counter for PageWrite used to accumulate the number of 

I PageRead lO's currently outstanding. 

j -max N 

I indicates that the maximum depth for the specified system-wide optimization entry 

j should be set to n. If this depth is reached then full optimization of this 10 

I type will be done system wide for all drives. 

j -response N, -rsp N 

I defines the optimization maximum response value. This value is the multiplier to 

j be used for an IO_TYPE queue load of a single request. 

I ACCESS REQUIRED 

j This command requires access to the hphcs_ gate. 

I NOTES 

I Refer to the Multics System Maintenance Procedures manual. Order No. AM81 for 

I a description of disk tuning techniques. 
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Name: tune_work class, twc 

SYNTAX AS A COMMAND 

twc -work__ciass N -control_args 

FUNCTION 

sets or changes the scheduling parameters for a single work class. 

ARGUMENTS 

-work_class N, -wc N 

specifies llie work class for which scheduling parameters are to be set 

CONTROL ARGUMENTS 

are the parameters to be set, and can be chosen from the following (at least one 
must be specified): 

-governed STR, -gv STR 

controls the limitation of CPU resources to the work class. STR can be "off," in 
which case there is no limitation for the work class; or STR can be a number 
between one and 100, which re^n^esrats a percentage of total system CPU time. In 
this case, the work class is limited to the specified percentage of total system 
CPU time. 

-int^response N, -ir N 

is the desired response time, in decimal seconds, after an interaction. 

-int_quantum N, -iq N 

is the quantum (time slice), in decimal seconds, given after an interaction. 

-int_queue STR 

controls the use of the interactive scheduler queue by users in the work class. 
STR can be "on", in which case users in the work class who have interacted 
recently are given priority over users in all work classes who have not interacted 
recently. STR can also be "off", in which case users in the work class who have 
interacted recently do not receive priority. The default is "off" for governed 
work classes and "on" for all other work classes. 

-response N, -r N 

is the time, in decimal seconds, between successive quanta. 

-quantum N, -q N 

is the quantum, in decimal seconds, given when an interaction has not just 
occurred. 

-pin^weight N, -pw N 

sets the pin weight of the work class to N. The default is 3 for the Initializer, 
and 0 for all other work classes. 
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-post_purge STR, -pp STR 

controls post purging of processes in the work class, where STR can be "on" or 
"off." If on, processes are post purged if post purging is enabled for the system; 
if off, processes are not post purged. 

-realtime STR, -realt STR 

places the work class in realtime mode if STR is "on"; removes the work class 
from realtime mode if STR is "off." 

-wc_max_eligible N 

applies eligibility constraints to processes in the work class, where N is an integer. 
If N is nonzero, no more than N processes are eligible at one time; if N is zero, 
only system-wide eligibility constraints are applied. 

ACCESS REQUIRED 

You need access to hphcs_. 

NOTES 

If the system scheduler is in percent mode, and the specified work class is not in 
realtime mode, the values of int_response, int_quantum, response, quantum, and 
wc_max_eligible have no effect on the system's operation. 

If the system scheduler is in deadline mode, or the specified work class is in realtime 
mode, the values of governed have no effect on the system's operation. 

This command is useful for setting scheduler parameters on a temporary basis. 
Parameters set by it are overridden by the values in the master group table (MGT) at 
shift change time, if a new MGT is installed, or if the operator issues the conmiand 
line "maxu auto." 



Name: unlock mca 

SYNTAX AS A COMMAND 
unlock_mca mca__number 
FUNCT/ON 

unlocks (enables) input to the maintenance channel adapter (MCA) specified by the 
argument 
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ARGUMENTS 
mca_number 

is the decimal number of the MCA to be unlocked. 



Name: imwire^pages 
SYNTAX AS A COMMAND 
unwire^pages path 

FUNCT/ON 

reverses the effect of the wire_pages command. All pages that were wired are unwired 
(i.e., no longer guaranteed to remain in main memory). 

ARGUMENTS 

path 

is the pathname of the segment whose pages are to be unwired. 
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Name: up ctr 

SYNTAX AS A COMMAND 

up_ctr 

FUNCTION 

is called by biller.ec at the end of a billing period. For each requisition in the 
reqfile, the up_ctr command adds "charges this month" to "charges this requisition" 
and resets "charges this month" to zero. It prints one number, the total of all 
"charges this month" fields. 



Name: update mail ^table_^eiitry 

SYNTAX AS A COMMAND 

update_mai l_tabl e_entry name {address} {-control_args} 
FUNCTION 



modifies an entry in the mail table. 

ARGUMENTS 

name 

specifies the name of the mail table entry which is to be updated. The name 
must be enclosed in quotation marks if it contains blank spaces. If the name is 
an alias, the associated normal entry is updated. 

address 

is a destination specifier, that is, a mailing address in the form, used by the 
-mailbox or -user control arguments (see below). If this is given, it becomes the 
new mail address of the entry. 

CONTROL ARGUMENTS 

-acs_path path 

specifies the Access Control Segment (ACS) which controls who may update the 
entry's mail address, rw access to the ACS indicates that a user may update the 
entry. If path is the null string there will be no ACS, and only system 
administrators (anyone with access to mail_table_priv_) may update the entry. 

-alias name 

specifies an alternate name for the entry. If this is specified multiple times, each 
alias is added. 



2-547 



GB64-00 



update_mail_table_entry update_maiLtable_entry 



-delete_alias name 

causes the specified alternate name to be removed from the entry. In order to 
maintain consistency with the person name table (PNT), this alias may not be the 
user's login alias. 

-log path 

specifies the pathname of a logbox and is equivalent to: 

-mai Ibox >udd>Project__id>Person_id>Person_i d .sv.mbx 

If this used, the pathname specified becomes the new mail address of the entry. 

-mailbox path, -mbx path 

specifies the pathname of a mailbox. The suffix "mbx" is added if necessary. If 
this is used, the pathname specified becomes the new mail address of the entry. 

-mailing_list path, -mis path 

specifies the name of a mailing list. The suffix "mis" is added if necessary. The 
archive component pathname convention is accepted. If this control argument is 
used, the pathname specified becomes the new mail address of the entry. 

-meeting path, -mtg path 

specifies the pathname of a Forum meeting. The suffix "control" is added if 
necessary. If this is used, the pathname specified becomes the new mail address 
of the entry. 

-save path, -sv path 

specifies the pathname of a savebox. The suffix "sv.mbx" is added if necessary. 
If this is used, the pathname specified becomes the new mail address of the 
entry. 

STR -at FSystem {-via RelayN...-via Relayl] 

specifies an address on another computer system. STR identifies the user (or 
group of users) to receive the message and is not interpreted in any way by the 
local system. FSystem is the name of the foreign system where the address is 
located. If the optional -via control arguments are not present, FSystem must be 
one of the names of a foreign system in the local system's network information 
table (NIT). If, however, the -via control arguments are specified, the foreign 
system name does not need to be known to the local system. 

If the -via control arguments are specified, they identify an explicit route to be 
used to reach the foreign system. In this case, Relayl must be one of the names 
of a foreign system in the local system's NIT. Mail destined for this foreign 
address is forwarded to the system identified as Relayl. From there it is 
forwarded to the system identified as Reiay2, etc. until it reaches the system 
identified as RelayN, where it is delivered to the system on which the foreign 
address actually resides. When the NIT is queried for either FSystem or Relayl, 
the query is performed in a case insensitive manner. 
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-user Person_id.Project_id 

specifies the given user's default mailbox under the specified project. This control 
argument is equivalent to: 

-mai Ibox >udd>Proj ect_i d>Person_i d>Person_i d .mbx 

If this is used, the pathname indicated becomes the new mail address of the 
entry. 

ACCESS REQUIRED 

The user must have e access to the gate mail_table_priv_. 

EXAMPLES 

The command line 

update_ma i l_tabl e__entry "John Jones" -alias JJ 

adds the name JJ to the entry John Jones. 
The command line 

update_ma i l_tabl e_entry "John Jones" JJones. Sales 

changes the mailing address asociated with John Jones to JJones.Sales. 



Name: usage and revenue 

SYNTAX AS A COMMAND 

usage__and_revenue control data {old__data} 
FUNCTION 

prints out a report of system usage and revenue broken down by groups of users. 
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The following lines must be added to master.ec and biller.ec before this command can 
be invoked. To master.ec add: 

f i le__output usage_and__revenue. report 

usage_and_revenue usage__and_revenue. control today .use__total s 

yesterday .use_total s 
consol e__output 

To biller.ec add: 

f i le_output month ly_usage_and_revenue. report 
usage_and_revenue usage__and_revenue. control today .use_tota Is 
consol e_output 



ARGUMENTS 
control 

is the pathname of an ASCII file that defines the groups of users for the report. 

data 

is the pathname of a copy of the system use_totals month-to-date statistical data 
base. 

old_data 

is the pathname of an earlier copy of the system use_totals month-to-date 
statistical data base. 

NOTES 

If both the data and old_data arguments are given, a daily report is produced showing 
the incremental system usage between the time old_data was created and the time data 
was created. If only the data argument is given, a monthly report is produced 
showing the month-to-date usage at the time data was created. 

The control file may specify up to nine groups of users to be shown in the report. 
Each line of the control file specifies one group; each group consists of one or more 
of the usage bins from the iise_totals data base. The format of a control file line is: 

Group t i 1 1 e:user 1 , user 2, . . . ,userN 

Lines beginning with an asterisk (♦) are ignored. The groups appear in the report in 
the same order in which they appear in the control file. 

where: 

group title 

is the title used to identify the group in the report. The maximum length is 24 
(spaces are allowed, see "Example" below). 
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useri 

are the names of the usage bins in the iise_totals data base that are to be 
included in this group. These are the names specified in the control file for 
reset_use_totals. If useri is enclosed in quotes, it specifies a group that is already 
defined in the control file and all the bins that go into that group also go into 
this group. (See "Example" below.) 

EXAMPLES 

If use_totals has bins labeled "Staff," "Users," and "Other," the control file: 



Staff Use:Staff 

Non-Staff Use:Users, Other 

Total :"Staff Use" , "Non-Staff Use" 



results in a report with three groups, one containing one usage bin (Staff), one 
containing two usage bins (Users+Other), and one containing three usage bins 
(Staff+Users+Other). 

A facility is provided to add notes or messages to the report If a segment named 
usage_and_revenue_footnote exists in the caller's working directory, its contents are 
printed at the end of the report. 



Name: usage total 

SYNTAX AS A COMMAND 

usage_total sat_path pdt_dir projfile use_totals 

FUNCTION 

scans all PDTs and places month-to-date system usage figures in a statistical data base. 

ARGUMENTS 

pdt_dir 

is the pathname of the directory in which the PDTs are located, 
projfile 

is the pathname of the project file. 
sat_pat 

is the pathname of the SAT. 
use_totals 

is the pathname of the statistics data segment. 
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NOTES 

This command is executed by the crank (in master.ec). The iise_totals segment is 

today. use_ totals, which is subsequently used as input to the system_daily_report 
program. 



Name: vtoc buffer meters 

SYNTAX AS A COMMAND 

vtoc_buf f er_meters {-control _arg} 

FUNCTION 

provides information about the utilization of volume table of contents (VTOC) buffers. 

CONTROL ARGUMENTS 

-report_reset, -rr 

generates a full report and then performs the reset operation. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 

the last call with -reset specified. If -reset has never been given in a process, it 

is equivalent to having been specified at system initialization time. 

ACCESS RQUIRED 

This command requires access to phcs_ or metering gate . 
NOTES 

If the vtoc_buffer_meters command is given with no control argument, it prints a full 
report. 

The following are brief descriptions of the metering variables printed out by the 

vtoc_buffeT_meteTs command. 

The first section of the output (labeled "Routine") displays the number of calls to 
VTOC buffer management routines. In each of these, the data is presented as number 
of calls and as average time between calls (ATB). The routines included are the 
following: 

get_vtoce 

called to read a VTOC entry, waiting for the I/O if the desired VTOCE entry is 
not already in a VTOC buffer. 
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put_vtoce 

called to write a VTOC entry without waiting for the I/O to complete. 
alloc_and_put_vtoce 

called to obtain a free VTOC entry, read the VTOC entry, and write it back to 
disk. 

free_vtoce 

called to return a VTOC entry to the free pool after nulling it and writing the 
nulled, entry to disk. 

await_vtoce 

called to await the completion of a VTOC write I/O generated by a previous call 
(e.g., to put_vtoce). 

GET.BUFFERS 

an internal routine to obtain a VTOC buffer for a specified VTOC entry. It first 
checks whether a buffer is already assigned to. the VTOC entry (if so, this is 
considered a "Hit"). If a buffer is not assigned, the routine selects one for the 
VTOC entry. 

WAIT 

an internal procedure to wait for completion of all I/Os for a given VTOC 

buffer. "TC Waits" are the number of times it was necessary to relinquish the 
CPU to wait for I/O completion. 



The next section of the output (labeled "Buffer Allocation") displays data on the 
performance of the buffer selection algorithm (the routine GET_BUFFERS). 

Steps 

is the number of times a buffer was examined by the selection algorithm. 
Skips 

is the number of times a buffer was skipped by the selection algorithm. This is 
refined by the reason for the skip, as follows: 

OS - an I/O was in progress for the buffer. 

hot - the buffer contained a VTOC entry that could not be written to disk 
because of irrecoverable write errors. 

wait - some process was waiting for completion of I/O activity to this buffer. 

The last section of the output (labelled "Disk I/Os") lists the number of disk reads 
and writes to the VTOC. 
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EXAMPLES 

The following is an example of the information printed when the vtoc_buffer_meters 

command is invoked with no control argument: (See Appendix A for a representation 

of the configuration deck used to create the system from which the metering sample 
was taken.) 



Total metering time: 0:15*35 

Routine # calls ATB (sec) 

get_vtoce 7367 0.1 3 

put_vtoce 0 0.00 

al loc_and_put_vtoce 732 1.28 

free_vtoce 6^2 1.^*6 

awa i t_vtoce 805 1 . 1 6 

GET_BUFFERS 17187 O.05 9820 Hits 

( 57-1% of calls) 
WAIT 6291 0.15 6291 TC Waits 

(100.0% of calls) 



Buffer Al location 



Disk l/Os 



# ATB (sec) 



Steps 10106 0.09 

Skips 2739 0.31* 27.1% of steps 

OS 2516 0.37 91 .9% of skips 

hot 0 0.00 0.0% of skips 

wait 223 ^.19 8.1% of skips 



# ATB (sec) 



Reads 52l8 O.I8 

Writes i»601 0.20 
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Name: vtoc pathname 

SYNTAX AS A COMMAND 

vtoc_pathname vol name vtocx {-control_arg} 
vtoc_pathname pvtx vtocx {-control_arg} 

FUNCT/ON 

determines the pathname of a segment from the location of its VTOC entry (VTOCE). 
Specify the location of the VT<X)E by giving its volume name (or physical volume 
table index, if known) and an index into the VTOC of that volume. 

ARGUMENTS 

volname 

is the physical volume name of the volume on which the VTOCE resides. This 
volume must be mounted and must be part of a mounted logical volume. 

pvtx 

is the physical volume table index of the volume on which the VTOCE resides, if 
known, is the VTOC index of the VTOCE. You must give it in octal. 

vtocx 

is the VTOC index of the VTOCE. You must give it in octal. 
CONTROL ARGUMENTS 
-brief, -bf 

suppresses the printing of an error message when the VTOCE is free. 
ACCESS REQUIRED 

You need access to the phcs_ gate, since it must copy directories. 

NOTES 

Your process must have status access to each of the containing directories of the 
segment The command supplies "~NO-ACCESS-" as the entryname at the level at 
which further access is necessary, if needed; it gives "-NOT-LISTED-" as the 
entryname at that level if one of the containing directories specified in the VTOCE 
does not exist in its containing directory; and it provides "-????-" as the entryname at 
any level below that at which either of these problems occurs. 
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Name: vtocx to record 

SYNTAX AS A COMMAND 

vtocx__to_record vtoc_index {dev i ce__name} 

FUNCTION 

converts an octal VTOCE to index a Multics record number and sector offset 

ARGUMENTS 

vtoc_index 

is the octal VTOCE index. 

device_name 

is a valid device name (e.g.. •'m400*', "m451"). 



Name: wire__pages 

SYNTAX AS A COMMAND 

wire_pages path {first_page n__pages} {-control__arg} 
FUNCT/ON 

wires all, or selected, pages of a s^ment into main memory. Such pages are not 
subject to removal by the page replacement algorithm. Wired pages remain in memory 
I until shutdown, or until unwired (see the imwire_pages command). 

ARGUMENTS 

path 

is the pathname of the segment to be wired. Supervisor segments cannot be wired 
by this conmiand. 

first_page 

specifies the page nimiber of the first page to be wired. The first page of a 

segment is page zero. If you give first_page, give n_pages. If first_page ends 

with a decimal point, it is treated as a decimal number; otherwise it is treated as 

an octal number. (Default* to wire all pages) 

n_pages 

specifies the number of pages to be wired. If n_pages ends with a decimal point, 
it is treated as a decimal number; otherwise it is treated as an octal number. 
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CONTROL ARGUMENTS 
-text 

to specify that path is an object segment and that only the text section should be 
wired. The default is to wire the whole segment. 

ACCESS REQUIRED 

Use of this command requires re access to the hphcs_ gate. 



Name: work class meters, wcm 

SYNTAX AS A COMMAND 
wcm {-control_arg} 
FUNCTION 

prints certain information from the tc_data segment about each work class currently 
defined. 

CONTROL ARGUMENTS 

-report_reset, -rr 

generates a full report and then performs the reset operation. 

-reset, -rs 

resets the metering interval for the invoking process so that the interval begins at 
the last call with -reset specified. If -reset has never been given in a process, it 
is equivalent to having been specified at system initialization time. 

ACCESS REQUIRED 

This command requires access to phcs_ or metering_gate_. Additionally, in order for 
the command to print the names of the work classes, access to both the Master 
Group Table (MGT) and the answer table is required. These tables are located in the 
directory >system_control_l. 

NOTES 

If the work_class_meters command is given with no control argument, it prints a full 
report 

When the scheduler is operating in percent mode, percentages are computed against 
two different base CPU quantities. It is necessary to understand the differences 
between these quantities in order to interpret the output of work_class_meters. 
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One base quantity is the total system CPU time. This is simply the total realtime all 
CPUs have been active doing anything (including running an idle process). In any 
interval of time when there was no reconfiguration of CPUs, the total system CPU 
time is the product of the length of the interval and the number of CPUs. Another 
base quantity is nonidle CPU time. This is the total CPU time expended by all CPUs 
except when running an idle process. It is given by the total system CPU time minus 
the sum of all idle time reported by total_time_meters (MP Idle, Non-MP Idle, and 
Zero Idle). 

When the scheduler is operating in percent mode, it distributes CPU resources among 
contending work classes according to their guaranteed percentages. These percentages 
are percentages of total nonidle CPU time. So, if there are two work classes, each 
with a guarantee of 50 percent, and the system is 50 percent idle, each work class 
gets 25 percent of total system CPU time (assuming that there is enough demand for 
this to be possible). In this example, each work class is getting 50 percent of the 
nonidle CPU time, but only 25 percent of the total system CPU time. Another way 
of viewing this is that the guaranteed percentages define a relationship among work 
classes according to the ratio of percentages. That is, a work class with a guaranteed 
percentage of 10 percent gets about half as much CPU time as a work class with a 
guaranteed percentage of 20 percent, assuming sufficient demand by both. Further, this 
ratio is independent of the system load. 

The system administrator can limit the CPU resources consumed by a work class to a 
fixed percentage of the total system CPU time. The scheduler enforces this limitation, 
even at the expense of going idle. That is, a work class with a maximum percentage 
of 10 percent gets no more than 10 percent of the total CPU time in any interval, 
regardless of load. Excess CPU time is distributed among work classes with no 
maximum percentage, according to their guaranteed percentages. If this cannot be 
done, the excess CPU time become idle time. 

At any time one or more work classes may be a realtime work class with specified 
response time and quanta. A process in such a work class is low priority until its 
deadline arrives, at which time it is made eligible regardless of any other constraints. 
The remainder of the work classes are scheduled either by percentage of CPU time 
(percentage mode) or by soft deadlines (deadline mode). 

The following parameters are always displayed for each work class. 

WC 

is the number of the work class. 
%GUAR 

is the percentage of nonidle CPU time guaranteed to the work class if the 
scheduler is being operated in percent mode and if there is sufficient demand by 
the work class for this to be possible. 

%MAX 

is the maximum percentage of total CPU time allowed by the system administrator 
to be consimied by this work class. This field is blank if the work class has no 
limitation on CPU consumption. 
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%TCPU 

is the percentage of total CPU time actually received by this work class in the 
metering interval. 

V/ELIG 

is the average amount of CPU time used per eligibility quantum. 

PW 

is the pin weight, or number of free laps for pages brought into memory. 



The following parameters are always displayed for realtime work classes, and are 
displayed for other work classes only if the scheduler is operating in deadline mode. 

IRESP 

is the response time (in seconds) specified for the work class after an interaction. 
IQUANT 

is the initial quantum (in seconds) for the work cto after an interaction. 
RESP 

is the specified delay (in seconds) between subsequent quanta. 
QUANT 

is the value (in seconds) of subsequent quanta. 



The following parameters are displayed when the scheduler is operating in either 
deadline or percentage mode. 

P 

if printed, members of the work class are post purged. 

M 

is the max_eligible limit per work class. A zero means the work class has no 
particular limit. 

R2 

if printed, the members of the work class are scheduled in realtime mode. They 
are made eligible at or before their deadlines. 

I 

if printed, members of the work class are given scheduler priority after 
interactions. 

LCG 

are the load control groups that are placed in the work class. If the LCG name 
is parenthesized, only the absentee processes in the LCG are placed in the work 
class. 
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EXAMPLES 

The following is an example of the information printed when the work_class_meters 
command is invoked with no control argument. The scheduler is operating in 
percentage mode. (See Appendix A for a representation of the configuration deck used 
to create the system from which the metering sample was taken.) 

Total metering time 0:15:35 
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Name: write acct bill 

SYNTAX AS A COMMAND 
wr i te_acct__bi 1 1 mm yy 
FUNCTION 

produces a bill for each external account number. Each bill contains one line for each 
Multics account 

ARGUMENTS 

mm 

is a two-digit month designation. 

yy 

are the last two digits of the year. 
NOTES 

The input to this program is the reqfile segment in the working directory. 

The output is on the switches named bill and mailing_copy, which must have been 
previously attached. 

This com_mand is used by biller=ec to create the bill and mailing_copy segments. The 
two segments differ in that mailing_copy has a page containing the mailing address of 
the intended recipient of the bill. 

The operation of this command depends on the proper attachment of the I/O switches 
(by biller.ec). 



Name: write billing smnmary 

SYNTAX AS A COMMAND 

wr i te_bi 1 1 i ng_summary mm yy 

FUNCT/ON 

this program is used to produce a one-line-per-account summary of the billing for 
external accounts. 
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ARGUMENTS 
mm 

is a two-digit month. 

yy 

is a two-digit year. 
NOTES 

Input to the program is the reqfile segment in the working directory. 

Output is on the sumry I/O switch, which must have been previously attached. 

This command is used by biller.ec to create the msum segment 



Name: write notify test 

SYNTAX 

wr i te_not ! f y_test {cpu_str} {-contro1_args} 
FUNCTION 

test the ability of the DPS 8 CPU and SCU interface to selectively clear CACHE 
when another active unit writes into main memory. 

ARGUMENTS 

cpu_str 

this is a character string of CPUs to use for testing. At least two CPUs are 
required, and one must be a DPS 8. The default is to select all the DPS 8 CPUs 
on the system. If only one DPS 8 CPU is found online, a L68 is used as the 
second processor. If there is only one CPU on the system or there are no DPS 8 
CPUs, the test will not run. 

CONTROL ARGUMENTS 

-brief -bf 

displays the brief form of errors and meters. This control argument is the 
default 

-deactivation_coimt -de N 

deactivates the data segment N times. This deactivation changes the location of 
the test page in main m.emory. The default is 1% of the total online pages. 
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-loop_count -Ic N 

loops N times before deactivating the segment. The default is 10. 

-long -Ig 

displays the long form of errors and meters, 
-meter 

displays the memory utilization percentages. If the -long control argument has 
been given, the actual pages and address lines are displayed. 

-v^?ord_increment, -wi N 

uses N as the word increment for the test page. N is a decimal number greater 
than 0 and less than 1023. The default is 52. 

-work_class 

runs the test in N work class. N is a decimal number from 0 to the highest 
work class number (16 max). The default is to run in the highest numbered 
realtime work class. Exiting from the test causes the work class to revert back to 
the original work class. 

ACCESS REQUIRED 

This command requires phcs_ and hphcs_ access. 
NOTES 

When invoked as an active function, write_notify_test returns the r&sults of the t^t 
If no errors are found, the return string is the word "passed". If the test detects 
errors, the first word of the return string is "failed". It is followed by the failing 
unit or units: 

failed CPU_A 

or 

fai led CPU_A SCU_B 

This test assumes that a write notify problem is address line dependent rather than 
memory dependent. Not all addresses or memory addresses are checked. The defaults 
listed cause a random selection of address lines. The use of the -meter and -long 
control arguments display the address lines (0 through 13) used for the test page. The 
-word_increment control argument controls the address lines 14 through 23. 

The test consists of three embedded loops. The outermost loop is controlled by the 
number of CPUs selected. The CPUs selected are divided into pairs and each pair is 
iterated through the next two sub-loops. For example: CPUs a, b, c, and d have been 
selected. The first pair is ab, the next is be, and the last is cd. This aids in 
diagnostics. 
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The -deactivation_count control argument controls the second loop, the deactivation 
loop. This loop deactivates the test page in main memory, enabling the system to 
assign a new page address for testing. 

The -loop_count control argument controls the inner most loop, the read_v^rite loop. 
The first CPU in the pair writes the test page and the second CPU reads the test 
page. Next, the second CPU in the pair writes the test page and the first CPU reads 
the test page. Meters are displayed for each pair of CPUs. 



Name: write user usage report 

SYNTAX AS A COMMAND 

wr i te_user_usage_repor t sat__path pdt_dir reqfile projfile miscfile 
FUNCTION 

produces one or more pages for each project, giving the usage for the month for all 
users. 

ARGUMENTS 
sat_path 

is the pathname of a copy of the SAT. This data base contains a list indicating 
the valid projects and the projects deleted during the month. 

pdt_dir 

is the pathname of the directory where the copies of the PDTs are found. These 
segments contain per-user virtual CPU, memory units, and terminal usage for each 
project. 

reqfile 

is the pathname of the reqfile segment. This segment contains per-account 
requisition information. 

projfile 

is the pathname of the projfile segment. This segment contains per-project 
information. 

miscfile 

is the pathname of the miscfile segment. This segment contains miscellaneous 
charges and detailed information for the month for each project 
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NOTES 

The command writes its output on four switches, named: long^bill, mailing_copy, 
short_bill, and both_bills. These switches must have been previously attached (all I/O 
attachments are the responsibility of the caller). Output intended for both the long 
and short versions of the bill is written on the both_bills switch. The long version of 
the bill is written on the long_bill switch. This version has from one to four sections 
per project to include: 

summary of total charges (one line per user) 

summary of Interactive charges (one line per shift per user) 

summary of interactive charges (one line per queue per user) 

summary of I/O daemon charges (one line per queue per user) 

The mailing copy version of the bill (written on the mailing_copy switch) includes all 
of the above, plus the following: 

1. Page containing the mailing address of the intended recipient precedes the section 
for each project 

2. Current billing rates at the site are printed at the end of the total-charge 
summary. 

3. Contents of the billing_footnote segment (if it exists) are printed in the 
total-charge summary, after the billing rates. The billing_footnote segment 
contains announcement material for all project supervisors. 

The short version of the bill (written on the short_bill switch) consists of the 
per-project total-charge summary followed by a grand total page. 

If a user entry appears in a PDT for which there is no reqfile or projfile entry, the 
command types out an error message and aborts. 

If the calculated total dollar figure for an account (the sum of the user dollar figures 

in the PDT entries) does not match the total dollar figure kept in the reqfile, an 
error message is printed giving both totals, and the command continues using the total 
dollar figure from reqfile. 

It should be noted that, since the charges for each user are computed and stored as 
floating-point binary numbers, some rounding occurs during the conversion of each 
user's usage figures to dollars and cents for printing. Thus, discrepancies occur 
between the sum of the printed user usage figures and the total usage figure for the 
account The total figure is the one that is billed. 

This command is used by biller.ec to create the long_bill, short_bill, and mailing_copy 
segments. 

The operation of this command depends on the proper attachment of the I/O switches 
(by biller.ec). 
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